CRD Specification

ApplicationPersona and ClusterPersona Custom Resource Definitions

Dorgu extends Kubernetes with five Custom Resource Definitions (CRDs) that capture application identity, cluster context, and the self-healing record. These CRDs are the central data model that connects the CLI, Operator, and integrations — and they mean your incident history and remediation record live in your own cluster, not a vendor’s database.

CRD Overview

CRD	Scope	Purpose
ApplicationPersona	Namespaced	A single application’s desired operational profile and the Operator’s observed state
ClusterPersona	Cluster	Cluster-level identity: nodes, add-ons, capacity, platform, and policy
IncidentMemory	Namespaced	A detected incident, its diagnosed root cause, and how it was resolved
RemediationAction	Namespaced	A proposed fix, its approval state, and its verification outcome
DorguEvent	Namespaced	A classified, correlated Kubernetes event, bounded by age and by count

The primary CRD is ApplicationPersona, which describes a single application’s desired operational profile and the Operator’s observed state. ClusterPersona captures cluster-level context. The remaining three are the self-healing loop’s memory — see Self-healing.

Ownership Model

The spec and status of an ApplicationPersona are owned by different actors. This separation is fundamental to Dorgu’s design.

Actor	Writes	Mechanism
CLI / GitOps	spec	dorgu persona apply or ArgoCD sync
Operator	status	Status subresource updates during reconciliation
Operator	spec	Only via a human-approved RemediationAction

The CLI and GitOps tools define the desired state in the spec. The Operator observes the cluster and writes its findings to the status.

The one exception is remediation: when you approve a RemediationAction, the Operator applies that action’s JSON merge patch to the ApplicationPersona spec. That is a change you explicitly authorized, scoped to the fields in the proposal you reviewed. Nothing else lets the Operator write a spec.

The Operator never creates or modifies Deployments, Services, or any other workload resource, with or without approval. Its ClusterRole grants get, list, watch on apps/deployments and no write verb at all, so this is enforced by the API server. See security and permissions and the trust model.

If you manage personas through GitOps, an approved remediation’s patch will show as drift on the next sync — mirror the change back into your repo so your pipeline does not revert the fix. dorgu remediation approve --no-heal does not avoid this: it skips the Deployment patch only, and the persona is still updated by the Operator once the action is Approved.

The one case where the persona is not updated is a refusal: on a workload something else owns, approve writes nothing at all, neither the Deployment patch nor the status patch that would trigger the persona write. See the ownership model.

API Group and Scope

All CRDs belong to the dorgu.io/v1 API group.

Resource	Scope	Short name
ApplicationPersona	Namespaced	—
ClusterPersona	Cluster	—
IncidentMemory	Namespaced	im
RemediationAction	Namespaced	ra
DorguEvent	Namespaced	de

ApplicationPersonas live in the same namespace as the workloads they describe. ClusterPersona is cluster-scoped since it represents the entire cluster.

ApplicationPersona Spec Fields

The spec defines the desired operational profile for an application.

Field	Type	Required	Description
name	string	Yes	Application name. The value the operator resolves a Deployment by, via the discovery chain: app.kubernetes.io/name label, app label, metadata.name, then spec.selector.matchLabels. No label is required.
type	enum	Yes	api, web, worker, cron, daemon
tier	enum	No	critical, standard, best-effort
technical	object	No	Language, framework, and description
resources	object	No	CPU/memory requests and limits
scaling	object	No	minReplicas, maxReplicas, targetCPU, behavior
health	object	No	livenessPath, readinessPath, port
dependencies	array	No	Each entry: name, type, required, healthCheck
networking	object	No	Ports and ingress configuration
ownership	object	No	team, owner, repository, oncall
policies	object	No	Security context, deployment strategy, maintenance windows

ApplicationPersona Status Fields

The status is populated entirely by the Operator and reflects the observed state of the application.

Field	Type	Description
phase	enum	Pending, Active, Degraded, Failed
validation.passed	bool	Whether the latest validation passed
validation.issues[]	array	Each entry: severity, field, message, suggestion
health.status	enum	Healthy, Degraded, Unhealthy, Unknown
learned.resourceBaseline	object	avgCPU, avgMemory, peakCPU, peakMemory
argoCD.syncStatus	enum	Synced, OutOfSync, Unknown
argoCD.healthStatus	enum	Healthy, Degraded, Progressing, Missing, Unknown
recommendations[]	array	Improvement suggestions generated by the Operator

Full ApplicationPersona Example

A complete ApplicationPersona for a critical API service:

apiVersion: dorgu.io/v1
kind: ApplicationPersona
metadata:
  name: order-service
  namespace: commerce
spec:
  name: order-service
  version: "1.0"
  type: api
  tier: critical
  technical:
    language: go
    framework: gin
    description: Order processing and management service
  resources:
    requests:
      cpu: 100m
      memory: 128Mi
    limits:
      cpu: 500m
      memory: 512Mi
  scaling:
    minReplicas: 2
    maxReplicas: 10
    targetCPU: 70
    behavior: balanced
  health:
    livenessPath: /health
    readinessPath: /ready
    port: 8080
    startupGracePeriod: 30s
  dependencies:
    - name: postgres
      type: database
      required: true
    - name: redis
      type: cache
      required: false
  networking:
    ports:
      - port: 8080
        protocol: TCP
        purpose: HTTP API
      - port: 9090
        protocol: TCP
        purpose: Metrics
    ingress:
      enabled: true
      host: orders.example.com
      paths: ["/api/v1/orders"]
      tlsEnabled: true
  ownership:
    team: commerce-platform
    owner: [e-mail]
    repository: https://github.com/example/order-service
  policies:
    security:
      runAsNonRoot: true
      readOnlyRootFilesystem: true
      allowPrivilegeEscalation: false
    deployment:
      strategy: RollingUpdate
      maxSurge: "25%"
      maxUnavailable: "0"

ClusterPersona

ClusterPersona is a cluster-scoped resource that captures the overall cluster context. The Operator’s ClusterPersona controller automatically discovers and populates its status.

ClusterPersona Spec Fields

Field	Type	Required	Description
name	string	Yes	Human-readable cluster name
description	string	No	Cluster purpose or notes
environment	enum	No	development, staging, production
policies	object	No	Cluster-wide policy defaults
conventions	object	No	Naming and labeling conventions
defaults	object	No	Default values for ApplicationPersona fields
resourceQuotas	object	No	Cluster-level resource budget

ClusterPersona Status Fields

Field	Type	Description
phase	enum	Discovering, Ready, Degraded
nodes[]	array	Node names, roles, capacity, and conditions
resourceSummary	object	Allocatable CPU/memory across all nodes, plus what scheduled pods have requested. usedCPU and usedMemory hold requests, not consumption, despite the names
addons[]	array	Detected add-ons (ArgoCD, Prometheus, Grafana, etc.)
kubernetesVersion	string	Cluster Kubernetes version
platform	string	Detected platform (EKS, GKE, AKS, Kind, etc.)
applicationCount	int	Total number of managed ApplicationPersonas

The ClusterPersona controller reconciles every 5 minutes, scanning nodes, namespaces, and well-known add-on namespaces to keep the status current.

resourceSummary counted pods no node had accepted, until operator v0.11.0. cpuUtilization read 1689% on a cluster where 25% was requested, because every non-terminal pod had its requests summed against node allocatable and a pod sitting in the scheduling queue is non-terminal. That is not an over-estimate to be tightened: an unscheduled pod holds no allocation on any node, and because it can request more than the cluster owns, the error had no upper bound. Only pods a node has accepted are counted now.

The schema was right and the code did not match it: this field’s own description already said “the CPU claimed by the resource requests of scheduled pods”.

Two consequences worth knowing. This field feeds the dashboard’s cluster view, where a wrong number reads as authoritative in a way terminal output does not, so upgrade the operator if anything renders it. And dorgu health no longer reads it at all: as of CLI v0.12.0 the CLI computes saturation itself from nodes and pods, so the two are corrected from both ends and the terminal figure does not depend on which operator version happens to be installed.

Self-healing policy

spec.policies.selfHealing configures how the cluster heals.

Field	Type	Default	Description
enabled	bool	true	Not yet implemented — see the note below
mode	enum	propose	observe, propose, or auto-approve
trustLevel	int	2	Progressive trust level, 0–5
maxRemediationsPerHour	int	5	Rate limit per persona
excludeNamespaces	array	[]	Namespaces excluded from remediation
rollback.enabled	bool	true	Cluster-level default: roll back on degradation
rollback.healthCheckAfter	duration	—	How long to wait before verifying
rollback.maxRetries	int	1	Rollback attempt limit

mode is enforced by the proposer: observe records the incident and proposes nothing, propose proposes with approval required, and auto-approve is not implemented — it is accepted but degraded to propose with a warning. maxRemediationsPerHour and excludeNamespaces are enforced by the safety checker. enabled and trustLevel are not enforced: trustLevel is only fed to the AI planner as context, and detection/diagnosis/proposal run regardless of enabled — use mode: observe to stop at diagnosis. The operator’s auto-created persona uses mode: propose.

IncidentMemory

IncidentMemory is the record of a detected problem: what was seen, what caused it, and how it ended. It is created and maintained by the operator’s health-check reconciler. Read them with dorgu incidents.

Spec Fields

Field	Type	Required	Description
personaRef	object	Yes	kind (ApplicationPersona or ClusterPersona), name, namespace. On an unattributed incident it names the workload, and no persona of that name need exist.
attribution	enum	No	persona or unattributed. See below.
category	enum	Yes	resource, scaling, health, security, deployment, dependency, node, controlplane
severity	enum	Yes	info, warning, critical
detection	object	Yes	signal, source, firstSeen, lastSeen, affectedResources[]
rootCause	object	No	summary, confidence, provider, contributing[]
relatedResources	array	No	Other Kubernetes resources involved
resolution	object	No	action, remediationRef, appliedAt, outcome, duration

rootCause.provider is rule-based or ai-enhanced. resolution.outcome is resolved, partial, failed, or rollback — written by the remediation controller when the loop finishes.

Status Fields

Field	Type	Description
phase	enum	Detected, Investigating, Resolved, Recurring
occurrenceCount	int	How many times this incident has been detected
lastOccurrence	timestamp	Most recent detection
conditions[]	array	Standard Kubernetes conditions

Attribution

spec.attribution records how confidently the incident was tied to an application, and is mirrored to the label dorgu.io/attribution so it is one query:

Value	Meaning
persona	personaRef names an ApplicationPersona that exists.
unattributed	No single persona claimed the signals, so the incident is recorded against the workload rather than folded into a neighbouring application’s incident. A real outage Dorgu can see but cannot diagnose or remediate: no RemediationAction is proposed.

An unattributed incident closes once an attributed one is tracking the same workload, and its resolution.action says handover rather than recovery, because nothing observed the workload.

kubectl get incidentmemory -A -l dorgu.io/attribution=unattributed

Resolution

An incident auto-resolves only on positive evidence of recovery: its signal absent for a 5-minute grace period, and its pods observed Ready, restart-free, and out of any waiting state for a 6-minute stability window. Anything else, including any failure to read the cluster, leaves it open. spec.resolution.action records the evidence as auto-resolved: <what was observed>.

attribution and evidence-based resolution are new in operator v0.10.0. In v0.9.0 an incident resolved on the absence of a signal alone, which a crash loop in backoff could produce while still completely dead. See self-healing.

RemediationAction

RemediationAction is a proposed fix. The operator creates it, you approve or reject it, and the operator records what happened. Work with them via dorgu remediation.

Spec Fields

Field	Type	Required	Description
incidentRef	object	Yes	The IncidentMemory that triggered this remediation
personaRef	object	Yes	The persona to be remediated
trustLevel	int	Yes	Minimum trust level required to execute, 0–5
action	object	Yes	Single-action fallback: type, patch, prePatchState
steps[]	array	No	The ordered plan. When non-empty, this is the plan of record.
workloadRef	object	No	The live workload this remediation concerns, and who owns it. Written by operator v0.9.0+. See below.
planSource	enum	No	rule-based or ai-anthropic
planSummary	string	No	The AI’s root-cause and plan explanation
explanation	string	Yes	Human-readable reason for the proposal
confidence	string	Yes	Diagnosis confidence as a decimal string, e.g. "0.85"
approval	object	No	required (default true), deadline, autoApproveRule
rollback	object	No	enabled (default true), healthCheckAfter, maxRetries (default 1)

action.type is one of persona-update, notification, or git-pr. action.patch is a JSON merge patch applied to the Persona spec — never to a workload.

workloadRef Fields

The operator populates this from the live Deployment at proposal time. It exists because the persona is a point-in-time import that drifts from the running workload, so every stated fact and every blast-radius cap is grounded here rather than in the persona.

Field	Type	Required	Description
kind	enum	Yes	Deployment. The only kind resolved today.
name	string	Yes	The live Deployment’s metadata.name. Not the persona name: persona frontend commonly resolves to Deployment frontend-podinfo.
namespace	string	Yes	The Deployment’s namespace
container	string	No	The container whose resources were observed, and which a fix would target
managedBy	enum	Yes	helm, argocd, flux, kustomize, unmanaged, unknown. Defaults to unknown. kustomize is only set from an opt-in marker.
managedByDetail	string	No	The specific owner in prose, e.g. Helm release "frontend" in namespace apps. Max 253 characters.
observedResources	object	No	requests and limits, each a cpu/memory pair. An empty string means the workload does not set that key, which is distinct from a value of zero.
observedImage	string	No	The container’s live image reference including its tag. The only image Dorgu has read.
observedAt	timestamp	No	When the live workload was read

managedBy governs one thing: whether the CLI may patch the Deployment. Only unmanaged permits it. Everything else, including unknown and an entirely absent workloadRef, means Dorgu recommends and does not write.

Absent is treated as owned on purpose: it means either an operator older than v0.9.0 or a workload that could not be read, and neither is evidence that patching is safe. Enforced by CLI v0.10.0. See the ownership model.

It has no bearing on persona writes. A persona-update step patches the ApplicationPersona, the operator does that itself, and its autoExecutable semantics are unchanged whoever owns the workload.

Step Fields

Each entry in steps[]:

Field	Type	Description
order	int	1-based execution order
id	string	Stable per-plan step identifier
type	enum	persona-update, workload-apply, restart, scale, config-change, manual
description	string	Human-readable summary of the action
rationale	string	Why the step is proposed (the AI’s reasoning)
risk	enum	low, medium, high
autoExecutable	bool	Whether the operator may apply this step without external action
command	string	An optional ready-to-run kubectl command for an advisory step. Never executed by the operator or the CLI. Sanitized before storage and re-checked before display. Operator v0.8.0+.
patch	object	JSON merge patch for the Persona spec (persona-update steps)
prePatchState	object	Snapshot of the fields before the patch, used for rollback
safety[]	array	Guardrail verdicts on this step, one entry per field a guardrail ruled on. Optional; absent means no guardrail ruled. Operator v0.11.0+. See step safety fields.

autoExecutable may only be true on a persona-update step. This is enforced at the Kubernetes API server by a CEL validation rule on the CRD (!self.autoExecutable || self.type == 'persona-update'), not just in operator code. Every other step type is advisory, which is what preserves the operator’s guarantee that it never writes workloads.

On an owned workload, steps are reshaped before they are persisted. Where workloadRef.managedBy is anything but unmanaged, the operator drops the command from any step whose command writes to the cluster, rewrites description as what to change at the source (chart values for a Helm release, the Git manifests for an ArgoCD application), and appends one line to rationale on what a direct patch would have broken. Read-only commands such as kubectl logs survive. persona-update steps are never reshaped. See what changes about the plan.

Step Safety Fields

New in operator v0.11.0. Each entry in steps[].safety is one guardrail’s verdict on one field of that step.

Every value in this field is Dorgu’s own arithmetic. No part of it comes from a model, and the model is not permitted to characterise a guardrail’s verdict at all. That is why the field exists rather than being a sentence.

It replaces a [safety:blast-radius] … prefix that used to be spliced onto the front of rationale, a string the AI planner authors. A computed refusal therefore read as part of the model’s reasoning, one line below the model’s own claim that the same 16x change was “well within a 2x ceiling”, and nothing on the screen distinguished the measurement from the assertion. A verdict is not the plan’s to give, so it no longer arrives inside the plan’s prose.

Field	Type	Required	Description
rule	enum	Yes	Which guardrail ruled: blast-radius, plan-validation, or absent-field
verdict	enum	Yes	What happened to the requested value: clamped, rejected, or derived
field	string	Yes	The persona-spec path ruled on, for example spec.resources.limits.memory
baseline	string	No	The value the guardrail measured against: the live workload’s value where it could be read, the persona’s otherwise. Empty when the rule measured no change, since a derived patch has nothing to compare.
requested	string	No	The value the plan asked for. Empty when the plan named a change without giving a value.
permitted	string	No	The value that will actually be applied, and exactly what the step’s patch carries. Empty means nothing will be applied for this field.
ratio	string	No	The requested change as a multiple of baseline, for example 16.0x
maxRatio	string	No	The largest multiple the guardrail allows, for example 2.0x
message	string	Yes	Dorgu’s one-line rendering of the verdict, ready to print

rule

Value	The guardrail
blast-radius	The cap on how far one remediation may move a resource value in a single step: 2x the live container value for an increase, 50% for a decrease.
absent-field	A remediation may move a resource key the workload already sets but may never introduce one it does not. Recorded here alongside the prose it already produced.
plan-validation	The check that a plan diagnosing a resource change actually carries a patch that can be applied.

verdict

Value	Meaning
clamped	The guardrail refused the requested value and Dorgu substituted one it permits. permitted is what the patch carries, so the diff shows what will really happen.
rejected	The guardrail refused the requested value and nothing replaces it. The field is removed from the step’s patch, so it appears in no diff, and this entry is the only record that it was asked for.
derived	The plan named a change but carried no patch Dorgu could apply, so Dorgu computed the value itself from the live workload rather than persisting a fix that applies nothing.

spec:
  steps:
    - order: 1
      type: persona-update
      autoExecutable: true
      patch:
        spec:
          resources:
            limits:
              memory: 512Mi          # what `permitted` says, not what `requested` says
      safety:
        - rule: blast-radius
          verdict: clamped
          field: spec.resources.limits.memory
          baseline: 256Mi
          requested: 4Gi
          permitted: 512Mi
          ratio: 16.0x
          maxRatio: 2.0x
          message: "Blast-radius guardrail: the plan asked to set spec.resources.limits.memory to 4Gi, ..."
        - rule: absent-field
          verdict: rejected
          field: spec.resources.limits.cpu
          requested: 500m
          message: 'Left out: container "checkout" on checkout does not set cpu today, ...'

Optional and additive, so nothing has to migrate. safety is absent on every object an operator older than v0.11.0 wrote, and absent means no guardrail ruled. A client that does not know the field renders exactly as it did before and gains no safety key in JSON output. There is no version pinning between the CLI and the operator on account of it: see guardrail verdicts.

A step with no patch is removed from the plan; a step whose patch a guardrail emptied is kept. The difference is what the object is for. A persona-update step carrying no patch applies nothing and instructs nobody, since updating the ApplicationPersona is Dorgu’s own job, and it is what used to render as (no changes) underneath a plan that read like a fix. A step a guardrail emptied carries the record of which field was refused and why, which is the difference between a step that explains an absence and a step that is one.

How the CLI prints these: guardrail verdicts. How they are produced: guardrail verdicts as data.

Status Fields

Field	Type	Description
phase	enum	Pending, Approved, Applying, Verifying, Completed, RolledBack, Failed, Rejected, Expired
approvedBy	string	Who approved it — the CLI records cli-user
approvedAt	timestamp	When it was approved
appliedAt	timestamp	When the patch was applied
verificationResult	enum	Healthy, Degraded, Unknown
currentStep	int	1-based order of the step being executed
stepStatuses[]	array	Per-step order, phase (Pending, Applied, Verified, Failed, Skipped), appliedAt, verificationResult
conditions[]	array	Standard Kubernetes conditions: Applied, Verified, RolledBack

steps[] is populated, validated, and rendered by the CLI, and currentStep / stepStatuses[] exist in the schema — but the controller currently executes the single spec.action patch rather than walking the plan step by step. autoApproveRule is likewise present in the CRD and ignored by controllers: auto-approve graduation is not implemented.

DorguEvent

DorguEvent is a write-once, classified Kubernetes event record. The event pipeline watches core Kubernetes events, classifies them by severity and category, correlates them to a persona and incident where it can, and stores them. There is no status subresource, so the record is immutable.

Records are bounded by age and by count: dorguEvents.retention (default 24h) and dorguEvents.maxRecords (default 2000, oldest pruned first). A per-record spec.ttl overrides the age bound for that record. See DorguEvent retention.

Field	Type	Required	Description
severity	enum	Yes	info, warning, critical
category	enum	Yes	resource, scaling, health, security, deployment, dependency, node, controlplane
source	string	Yes	The detector that generated the event
message	string	Yes	Human-readable description
involvedObject	object	Yes	The Kubernetes resource the event relates to
personaRef	object	No	Linked persona, when one applies
incidentRef	object	No	Linked IncidentMemory, when correlated
eventTime	timestamp	Yes	When the original Kubernetes event occurred
k8sEventRef	string	No	Original Kubernetes Event UID, used for deduplication
ttl	duration	No	Per-record retention override. Absent means the operator’s dorguEvents.retention applies (default 24h).

Stream them live with dorgu watch events.