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 (use in-cluster address)
  hostAPI: http://kms.hanzo.svc.cluster.local/api

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

  # Authentication configuration
  authentication:
    universalAuth:
      credentialsRef:
        # K8s Secret containing clientId and clientSecret
        secretName: universal-auth-credentials
        secretNamespace: hanzo
      secretsScope:
        # KMS project to read from
        projectSlug: secrets-639-c
        # KMS environment
        envSlug: prod
        # Path within the project
        secretsPath: /example

  # 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	URL of the KMS API. Always use the in-cluster address for security.
Example	`http://kms.hanzo.svc.cluster.local/api`

`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 project slug
`envSlug`	`string`	Yes	Environment slug (`prod`, `staging`, `dev`)
`secretsPath`	`string`	Yes	Path within the project (e.g., `/chat`, `/`)

`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