GitOps kind reference

This page is the operator reference for the entity kinds Checkstack ships out of the box. Each kind has its own YAML schema and is registered by a built-in plugin. For the plugin-author side - registering your own kinds or extending an existing one - see GitOps entity kinds.

Descriptor envelope

All YAML descriptors follow the Kubernetes-inspired envelope format:

apiVersion: checkstack.io/v1alpha1    # Required. Must match a registered kind.
kind: System                           # Required. The entity kind name.
metadata:                              # Required. Common fields.
  name: my-system                      # Required. URL-safe identifier (lowercase, hyphens).
  title: My System                     # Optional. Human-readable display name.
  description: A brief description     # Optional.
  labels:                              # Optional. Key-value pairs for filtering.
    team: platform
  tags:                                # Optional. String tags.
    - production
spec:                                  # Kind-specific configuration.
  # ... fields defined by the kind's specSchema

Entity references

Use Kubernetes-style structured references to create dependencies between entities:

spec:
  healthcheck:
    - ref:
        kind: Healthcheck        # The kind of the referenced entity
        name: payment-db-check   # The metadata.name of the referenced entity

The reconciler builds a dependency graph from these refs and reconciles entities in topological order.

Secret references

Use ${{ secrets.NAME }} template syntax for sensitive values that should be resolved from the GitOps secret store. Secrets are only resolved in fields the registering plugin marks as secret in its config schema, so secrets never leak through display fields like metadata.title.

spec:
  config:
    password: "${{ secrets.my-database-password }}"
    connectionString: "postgres://user:${{ secrets.DB_PASS }}@host/db"

When a secret is rotated, all entities referencing it are automatically flagged for re-reconciliation on the next sync cycle.

Built-in kinds

kind: System (catalog)

Top-level system, the unit of organisation in Checkstack.

apiVersion: checkstack.io/v1alpha1
kind: System
metadata:
  name: payment-api
  title: Payment API
spec: {}

kind: Healthcheck (healthcheck)

A scheduled health check bound to a strategy and config.

apiVersion: checkstack.io/v1alpha1
kind: Healthcheck
metadata:
  name: payment-db-check
spec:
  strategy: postgres
  intervalSeconds: 60
  config:
    host: db.internal
    port: 5432
    database: payments
    user: monitor
    password: "${{ secrets.payment-db-password }}"

kind: SLO (slo)

Reliability targets bound to a system, optionally narrowed to a single healthcheck. The objective UUID is the entity ID in provenance, so renames preserve identity.

apiVersion: checkstack.io/v1alpha1
kind: SLO
metadata:
  name: payments-availability
spec:
  systemRef: { kind: System, name: payments-api }
  healthcheckRef: { kind: Healthcheck, name: payments-http } # optional
  target: 99.9
  windowDays: 30
  dependencyExclusion: strict # or "self-only"
  excludedDependencyRefs: # optional
    - { kind: System, name: third-party-payments }
  burnRateThresholds: # optional
    warningPercent: 50
    criticalPercent: 80
    fastBurnMultiplier: 5

kind: Satellite (satellite)

Metadata-only declaration of remote execution nodes. The bcrypt token is never expressed in YAML - the reconciler discards the random token issued at creation. Operators retrieve a working token via the Reset token button on the Satellites page. Runtime tags use the envelope’s metadata.labels (Record<string, string>), so there is no duplicate tags field on the spec.

apiVersion: checkstack.io/v1alpha1
kind: Satellite
metadata:
  name: eu-west-1
  labels:
    tier: prod
    region-group: emea
spec:
  region: eu-west-1

The reconciler adopts pre-existing satellites by metadata.name on first sync, so manually-created satellites are absorbed safely.

Built-in extensions

Extensions add namespaced fields to an existing kind. They appear under spec.<namespace>: in the descriptor.

Healthcheck.anomaly (anomaly)

Per-healthcheck anomaly defaults. Replaces the full template-level AnomalySettings record on every reconcile (GitOps is the source of truth; UI edits to managed entities are blocked).

apiVersion: checkstack.io/v1alpha1
kind: Healthcheck
metadata: { name: payment-db-check }
spec:
  # …strategy / intervalSeconds / config…
  anomaly:
    enabled: true
    sensitivity: 1
    confirmationWindow: 3
    baselineWindow: "7d"
    notify: true
    driftEnabled: true
    driftThreshold: 2
    fieldOverrides: # keyed by result field path
      latencyMs: { sensitivity: 0.5, driftThreshold: 4 }

System.healthcheck (healthcheck)

Bind health checks to a system, with optional threshold overrides.

apiVersion: checkstack.io/v1alpha1
kind: System
metadata: { name: payment-api }
spec:
  healthcheck:
    - ref: { kind: Healthcheck, name: payment-db-check }
      degradedThreshold: 2
      unhealthyThreshold: 5

System.dependencies (dependency)

Declares upstream system dependencies. The reconciler diffs the declared edges against the persisted ones where this system is the source, then applies create / update / delete to converge. Refs that resolve to the source system itself are rejected.

apiVersion: checkstack.io/v1alpha1
kind: System
metadata: { name: payments-api }
spec:
  dependencies:
    - targetRef: { kind: System, name: payments-db }
      impactType: critical # informational | degraded | critical
      transitive: false # follow multi-hop chains?
      label: "primary store" # optional

The Dependency Map UI disables Add/Edit/Delete for the source system’s upstream edges; downstream edges are gated per-row by the other system’s lock.

System.anomaly (anomaly)

Per-assignment anomaly overrides (“exceptions”), keyed by healthcheckRef. Each entry maps to one System to Healthcheck assignment and its AnomalySettings partial.

apiVersion: checkstack.io/v1alpha1
kind: System
metadata: { name: payment-api }
spec:
  anomaly:
    - healthcheckRef: { kind: Healthcheck, name: payment-db-check }
      enabled: false
      fieldOverrides:
        latencyMs: { sensitivity: 0.3 }

Kind Registry Browser

The Kind Registry page (accessible from the user menu) provides a live view of every registered kind on your instance, with the merged base + extension schema and an auto-generated YAML example. Use it to discover what kinds are available on your install, including those from third-party plugins.

See also

• GitOps entity kinds (developer) - registering custom kinds and extensions as a plugin author.