KMSSecret CRD

The KMSSecret Custom Resource Definition (CRD) enables automatic synchronization of secrets from Hanzo KMS to Kubernetes Secrets. The kms-operator watches for KMSSecret resources and keeps the target K8s Secrets up to date.

API Version

apiVersion: secrets.lux.network/v1alpha1
kind: KMSSecret

Full Spec

apiVersion: secrets.lux.network/v1alpha1
kind: KMSSecret
metadata:
  name: example-kms-sync
  namespace: hanzo
  labels:
    app.kubernetes.io/name: example
    app.kubernetes.io/component: secrets
    app.kubernetes.io/part-of: hanzo-platform
spec:
  # KMS API endpoint
  hostAPI: https://kms.hanzo.ai

  # How often to re-sync secrets (seconds)
  resyncInterval: 60

  # Authentication configuration
  authentication:
    universalAuth:
      credentialsRef:
        # K8s Secret containing clientId and clientSecret
        secretName: app-kms-auth
        secretNamespace: hanzo
      secretsScope:
        # KMS org to read from (matches the machine identity's owner)
        projectSlug: hanzo
        # KMS environment
        envSlug: production
        # Path within the org
        secretsPath: /example
        # Exact secret names to sync — KMS has no list endpoint, enumerate them
        keys:
          - EXAMPLE_API_KEY
          - EXAMPLE_DB_URL

  # Target K8s Secret
  managedSecretReference:
    # Name of the K8s Secret to create/update
    secretName: example-secrets
    # Namespace for the K8s Secret
    secretNamespace: hanzo
    # K8s Secret type
    secretType: Opaque
    # What happens when the KMSSecret CRD is deleted
    creationPolicy: Orphan

Field Reference

`spec.hostAPI`


Type	`string`
Required	Yes
Description	Base URL of the KMS API. The operator appends `/v1/kms`. In-cluster you may use `http://kms.hanzo.svc.cluster.local`.
Example	`https://kms.hanzo.ai`

`spec.resyncInterval`


Type	`integer`
Required	Yes
Description	Interval in seconds between secret re-sync operations.
Default	`60`
Minimum	`10`

`spec.authentication.universalAuth`

`credentialsRef`

Field	Type	Required	Description
`secretName`	`string`	Yes	K8s Secret containing Machine Identity credentials
`secretNamespace`	`string`	Yes	Namespace of the credentials Secret

The referenced Secret must contain two keys:

clientId — Machine Identity client ID
clientSecret — Machine Identity client secret

`secretsScope`

Field	Type	Required	Description
`projectSlug`	`string`	Yes	KMS org slug — maps to `{org}` and must match the identity's `owner`
`envSlug`	`string`	Yes	Environment — maps to `?env=` (`production`, `staging`, `dev`)
`secretsPath`	`string`	Yes	Path within the org (e.g., `/providers`, `/`)
`keys`	`string[]`	Yes	Exact secret names to sync (1–128). KMS has no list endpoint — enumerate every key

`spec.managedSecretReference`

Field	Type	Required	Description
`secretName`	`string`	Yes	Target K8s Secret name
`secretNamespace`	`string`	Yes	Target namespace
`secretType`	`string`	No	K8s Secret type. Default: `Opaque`
`creationPolicy`	`string`	No	`Orphan` or `Owner`. Default: `Owner` (deletes Secret with CRD)

Creation Policies

Policy	Behavior
`Owner`	K8s Secret is deleted when the KMSSecret CRD is deleted (default)
`Orphan`	K8s Secret survives CRD deletion. Recommended for production to prevent accidental secret loss.

Labeling Convention

All Hanzo services follow this labeling pattern:

labels:
  app.kubernetes.io/name: <service-name>
  app.kubernetes.io/component: secrets
  app.kubernetes.io/part-of: hanzo-platform

Troubleshooting

Secret not syncing

# Check KMSSecret status
kubectl describe kmssecret <name> -n hanzo

# Check kms-operator logs
kubectl logs -l app=kms-operator -n hanzo --tail=50

# Verify credentials are valid
kubectl get secret universal-auth-credentials -n hanzo -o jsonpath='{.data.clientId}' | base64 -d

Common errors

Error	Cause	Fix
`authentication failed`	Invalid or expired credentials	Regenerate Machine Identity credentials in KMS
`project not found`	Wrong `projectSlug`	Verify project slug in KMS UI
`path not found`	Empty or non-existent path	Create the path and add at least one secret in KMS
`forbidden`	Insufficient permissions	Grant the Machine Identity Viewer role on the project

Next Steps

Machine Identity authentication

Full inventory of services using KMS

IAM-specific secret management

KMSSecret CRD

On this page