CRD reference

Seven CRDs cover the full governance surface. The full per-field canonical reference lives at docs/operator/crd-reference.md.

This page summarises the spec shape of each CRD; consult the in-repo reference (or kubectl explain orbitalregproject.spec) for every default and validation rule.

OrbitalRegProject

apiVersion: orbitalreg.io/v1alpha1
kind: OrbitalRegProject
metadata:
  name: acme
spec:
  slug: acme                          # immutable post-create
  displayName: "Acme Corp"
  description: "Top-level project for Acme."
  ownerEmails:
    - platform@acme.example.com
status:
  projectID: 0e2…-…-…                # populated on first reconcile
  conditions:
    - type: Synced
      status: "True"
    - type: Ready
      status: "True"
  observedGeneration: 1

OrbitalRegRepository

apiVersion: orbitalreg.io/v1alpha1
kind: OrbitalRegRepository
metadata:
  name: acme-internal-maven
spec:
  projectRef:
    name: acme                        # sibling Project CR
  slug: internal-maven
  displayName: "Internal Maven"
  format: maven                       # one of 42 supported formats
  kind: local                         # local | remote | virtual
  upstreamUrl: ""                     # required for kind=remote
status:
  repositoryID: …

OrbitalRegServiceAccount

apiVersion: orbitalreg.io/v1alpha1
kind: OrbitalRegServiceAccount
metadata:
  name: ci-runner
spec:
  projectRef:
    name: acme
  name: ci-runner
  description: "GitLab CI runner pushing to acme/internal-maven"
  enabled: true
  scopes:
    - "push:project:acme:repo:internal-maven"
status:
  serviceAccountID: …

OrbitalRegServiceAccountToken

The only namespace-scoped CRD — its plaintext token is materialised into a Kubernetes Secret in the same namespace.

apiVersion: orbitalreg.io/v1alpha1
kind: OrbitalRegServiceAccountToken
metadata:
  name: ci-runner-token
  namespace: gitlab-runners
spec:
  serviceAccountRef:
    name: ci-runner                   # cluster-scoped SA CR
  name: ci-runner-2026-q2
  scopes:
    - "push:project:acme:repo:internal-maven"
  expiresIn: 90d
  secretName: orbitalreg-ci-runner    # default: <crname>-creds
status:
  tokenID: …
  specHash: sha256:…                  # rotation trigger
  secretRef:
    name: orbitalreg-ci-runner
    keys: [token, endpoint]

The Secret is owner-referenced so deletion garbage-collects it.

OrbitalRegRetentionPolicy

apiVersion: orbitalreg.io/v1alpha1
kind: OrbitalRegRetentionPolicy
metadata:
  name: snapshots-keep-7d
spec:
  repositoryRef:
    name: acme-internal-maven
  name: snapshots-keep-7d
  rules:
    - keep_by_age:
        max_age_days: 7
        match_path_regex: "-SNAPSHOT/"
status:
  policyID: …

A spec.name rename is in-place — the policy UUID stays stable so every retention_audit FK is preserved.

OrbitalRegSecurityBlock

apiVersion: orbitalreg.io/v1alpha1
kind: OrbitalRegSecurityBlock
metadata:
  name: malicious-2025-0042
spec:
  blockType: sha256                   # sha256 | path-glob | cve | repo
  pattern: "9f86d081…"
  repoRef:
    name: acme-internal-maven         # optional; omit for cluster-wide
  reason: "Confirmed-malicious sample from FAS-2025-0042"
  customerMessage: |
    This artifact was blocked because it matches a known supply-chain
    attack indicator. Contact security@example.com if you believe
    this is in error.
  cveID: ""                           # optional
  blockedUntil: "2026-12-31T00:00:00Z" # optional
  active: true
status:
  blockID: …

Mutable metadata (reason / customerMessage / cveID / blockedUntil / active) PATCHes in place. Match-expression fields (blockType / pattern / repoRef) force destroy/recreate so the audit-log invariant "block ID stays paired with its match expression" holds.

OrbitalRegWebhookSubscription

apiVersion: orbitalreg.io/v1alpha1
kind: OrbitalRegWebhookSubscription
metadata:
  name: soc-pipeline
spec:
  url: https://soc.example.com/orbitalreg/events
  hmacSecretRef:
    name: orbitalreg-soc-hmac
    namespace: orbitalreg-operator
    key: secret
  events:
    - artifact.uploaded
    - artifact.promoted
    - finding.threshold-exceeded
    - retention.deleted
status:
  subscriptionID: …

The HMAC secret is read from the referenced Kubernetes Secret and pushed to the API only on first create or when the Secret's metadata.resourceVersion advances. List responses return only has_secret: bool and the reconciler never reads it back, with a recovery path that re-pushes when an out-of-band SQL UPDATE clears the column.