Declaring resources

Declaring a resource for the Komodor Agentic Operation Platform (KAOP) means applying a Kubernetes custom resource — a Credential, an McpServer, or one of the other supported kinds — to a cluster running the operator described in Configuration clusters. The operator reconciles what you declare through the KAOP API and writes the result back onto the resource’s own status, so the manifest is the source of truth without a separate API call of your own.

How a declaration maps to KAOP

Every kind is in the agentops.komodor.io/v1alpha1 API group, and every resource is namespaced.
The namespace binds the resource to one account: the cluster install running in that namespace is tied to a single KAOP account.
spec.name is the resource’s name in KAOP and defaults to metadata.name. Changing spec.name does not rename anything — it points the declaration at a different name, so the old resource is left behind.
A field you set in spec is reapplied on every resync (operator.resyncInterval, default 5m), so an out-of-band change to it is corrected back. A field you leave unset stays under KAOP’s own control.
KAOP remains the validator. A spec the CRD’s schema accepts can still be rejected — the reason appears on the resource’s Synced condition.

Supported kinds

Kind	Declares	Related page
`Credential`	A stored value, delivered from a referenced Secret.	Credentials & secrets
`EvalFlow`	An evaluation that grades a set of agents’ runs against criteria, through one evaluator agent.	Evaluations
`GoldenScenario`	A single scored test case, tagged by domain.	—
`GoldenSuite`	A group of golden scenarios under one runner agent.	—
`Guardrail`	A rule that blocks, holds, redacts, or records a matched action for a set of agents.	Standards & Guardrails
`HostedAgent`	A hosted agent’s model, image, MCP servers, skills, and tools.	Build — how it works
`IncidentPipeline`	Routes an alert source to an orchestrator and specialist agents as an incident pipeline.	Incident management & troubleshooting
`IntegrationConnection`	A connection to a built-in integration provider, authenticated from a referenced Secret.	Integrations list
`KnowledgeBase`	A knowledge base agents retrieve from and cite.	Knowledge base
`McpGroup`	A named bundle of MCP servers with its own allow/deny rules.	Integration groups
`McpPolicy`	A tool-call policy enforced on one or more MCP targets.	MCP Gateway
`McpServer`	An upstream MCP server, its transport, and the credential it authenticates with.	MCP Gateway
`Module`	Turns on a module and holds its settings.	Modules & workflows
`ModuleWorkflowTemplate`	A reusable workflow template published under a module.	Modules & workflows
`NotificationSink`	A destination — a channel or your own endpoint — that receives KAOP’s events.	Outbound webhooks
`ReviewWorkflow`	Binds a set of repositories and reviewer agents for automated code review.	—
`Schedule`	Runs one agent on a recurring cron expression.	Triggers & schedules
`SelfHostedAgentSettings`	Settings for an agent that runs in your own infrastructure instead of KAOP’s.	Deployment methods
`Skill`	A versioned runbook or procedure agents can use.	Skills
`WebhookTrigger`	An inbound endpoint that starts an agent run from an HTTP request.	Integrations list

Every kind shares the same spec/status contract above. For the full set of fields a kind accepts, run kubectl explain <kind>.spec against a cluster that has the CRDs installed — each field carries its own description.

Annotated example

A Credential resolves its value from a Kubernetes Secret in its own namespace rather than holding it inline:

apiVersion: v1
kind: Secret
metadata:
  name: datadog-api-key
  namespace: agentops
type: Opaque
stringData:
  api-key: "<your Datadog API key>"
---
apiVersion: agentops.komodor.io/v1alpha1
kind: Credential
metadata:
  name: datadog-api
  namespace: agentops
spec:
  name: datadog-api
  valueSecretRef:
    name: datadog-api-key
    key: api-key

An McpServer then references that credential by name, alongside the fields that reach the upstream server itself:

apiVersion: agentops.komodor.io/v1alpha1
kind: McpServer
metadata:
  name: datadog-mcp
  namespace: agentops
spec:
  name: datadog-mcp
  url: https://mcp.datadoghq.com
  transport: http
  credentialRef: datadog-api
  deletionPolicy: orphan

Apply both and read back the result. SYNCED is a default-visible column; RESOURCE needs -o wide:

kubectl apply -f secret.yaml -f credential.yaml -f mcpserver.yaml

kubectl -n agentops get mcpservers -o wide
# NAME          SYNCED   RESOURCE             AGE
# datadog-mcp   True     mcp_server_01h...    14s

References between resources

A field ending in Ref — credentialRef, agentRef, mcpGroupRef, and the rest — resolves by the KAOP name of the resource it points at, not by the Kubernetes object name.

A reference naming something that does not exist yet reports WaitingForDependency on the Synced condition, and is retried on every resync rather than treated as a standing error.
A reference naming something that already exists but that this cluster does not declare reports Conflict. The existing resource is never taken over.

Secrets

Values are read from Secrets in the same namespace as the resource that references them, and the value never appears in the spec a cluster can read, nor in status. Rotation is detected through status.secretHashes — a per-field fingerprint of the last value pushed, so an unrotated Secret is a no-op resync rather than a repeated write.

Applying manifests with ArgoCD, Flux, or helm template rather than installing with Helm against a live cluster means the operator cannot read its own rotation-key Secret back on each upgrade. Create that Secret yourself and name it in rotationKey.existingSecret, or a fresh key is generated on every sync.

Reading status

The Synced condition reports whether KAOP matches the declared spec, with one of eight reasons:

Reason	Meaning	What to do
`Applied`	KAOP matches the spec.	Nothing — this is the steady state.
`Rejected`	KAOP’s own validator refused the declaration.	Read the condition’s `message` for the control plane’s reason, and fix the spec.
`Conflict`	The name is already claimed by another cluster’s resource, by a resource no cluster declares, or by an install whose claim this one may not take.	Resolve ownership at the resource or cluster named in the message.
`SecretMissing`	A referenced Secret or key is not in the resource’s namespace.	Create the Secret or key, or fix the reference.
`InstallPaused`	This cluster install is paused.	Resume the install to reapply the declaration.
`Error`	The operator could not attribute the failure to the declaration itself — an authentication failure, an exhausted retry, or a field role this build does not implement yet.	Check the operator’s logs and the cluster install’s credential.
`SecretRotated`	A referenced Secret’s value changed and was pushed again.	Nothing — this is a successful rotation, reported as its own event.
`WaitingForDependency`	A `*Ref` field names a resource that does not exist yet.	Create the referenced resource; the operator retries every resync.

status.resourceId is the KAOP id of the managed resource. For the control plane’s own wording on a failure, read the condition’s message with kubectl describe on the resource.

Deleting a declaration

The default deletionPolicy is delete: deleting the Kubernetes object removes the resource from KAOP too. Set deletionPolicy: orphan to leave the KAOP resource in place and release only the operator’s claim, so it can be managed elsewhere afterwards. Deletion still goes through while the cluster install is paused — a pause stops reassertion, not an explicit delete. kubectl delete --cascade=orphan is about Kubernetes-owned objects and does not reach the KAOP resource either way.

Operator scope and lifecycle

The operator watches only the namespace it is released into. Covering a second namespace means installing the chart again there with crds.install=false, since the CRDs are cluster-scoped and already belong to the first release.
Its permissions are namespace-scoped and narrow: no create or delete on the custom resources it reconciles, and get only on Secrets.
helm uninstall leaves the CRDs and your declared resources in place rather than deleting them.
A control plane behind an internal certificate authority needs caBundle.existingConfigMap pointed at a ConfigMap of PEM certificates, or the operator never becomes ready.
To check which build is running, read the image tag on the operator’s pod — it is distroless, so there is no shell to exec into instead.

Next steps

Configuration clusters

Connect a cluster and read its sync status.

Credentials & secrets

Manage credentials declared through this interface alongside the ones created in KAOP.

MCP Gateway

Configure governed access to the MCP servers a cluster can declare.

Security & Governance

Identity & access

Controls

Architecture considerations

How a declaration maps to KAOP

Supported kinds

Annotated example

References between resources

Secrets

Reading status

Deleting a declaration

Operator scope and lifecycle

Next steps

Configuration clusters

Credentials & secrets

MCP Gateway

​How a declaration maps to KAOP

​Supported kinds

​Annotated example

​References between resources

​Secrets

​Reading status

​Deleting a declaration

​Operator scope and lifecycle

​Next steps

Configuration clusters

Credentials & secrets

MCP Gateway

How a declaration maps to KAOP

Supported kinds

Annotated example

References between resources

Secrets

Reading status

Deleting a declaration

Operator scope and lifecycle

Next steps