Using the Hanzo KMSPushSecret CRD

Overview

Feedback
Push Secrets from a Kubernetes secret into Hanzo KMS.
Feedback
Manage secret lifecycle of pushed secrets in Hanzo KMS. When the Kubernetes secret is updated, the operator will automatically update the secrets in Hanzo KMS. Optionally, when the Kubernetes secret is deleted, the operator will delete the secrets in Hanzo KMS automatically.

Prerequisites

Feedback
A project within Hanzo KMS.
Feedback
A machine identity ready for use in Hanzo KMS that has permissions to create secrets in your project.
Feedback
The operator is installed on to your Kubernetes cluster.

Example usage

  apiVersion: secrets.kms.hanzo.ai/v1alpha1
  kind: Hanzo KMSPushSecret
  metadata:
    name: kms-push-secret-demo
  spec:
    resyncInterval: 1m # Remove this field to disable automatic reconciliation of the Hanzo KMSPushSecret CRD.
    hostAPI: https://app.kms.hanzo.ai/api

    # Optional, defaults to no replacement.
    updatePolicy: Replace # If set to replace, existing secrets inside Hanzo KMS will be replaced by the value of the PushSecret on sync.

    # Optional, defaults to no deletion.
    deletionPolicy: Delete # If set to delete, the secret(s) inside Hanzo KMS managed by the operator, will be deleted if the Hanzo KMSPushSecret CRD is deleted.

    destination:
      projectId: <project-id> # Either projectId or projectSlug is required
      projectSlug: <project-slug>
      environmentSlug: <env-slug>
      secretsPath: <secret-path>

    push:
      secret:
        secretName: push-secret-demo # Secret CRD
        secretNamespace: default

    # Only have one authentication method defined or you are likely to run into authentication issues.
    # Remove all except one authentication method.
    authentication:
      awsIamAuth:
        identityId: <machine-identity-id>
      azureAuth:
        identityId: <machine-identity-id>
      gcpIamAuth:
        identityId: <machine-identity-id>
        serviceAccountKeyFilePath: </path-to-service-account-key-file.json>
      gcpIdTokenAuth:
        identityId: <machine-identity-id>
      kubernetesAuth:
        identityId: <machine-identity-id>
        serviceAccountRef:
          name: <secret-name>
          namespace: <secret-namespace>
      ldapAuth:
        identityId: <machine-identity-id>
        credentialsRef:
          secretName: <secret-name> # ldap-auth-credentials
          secretNamespace: <secret-namespace> # default
      universalAuth:
        credentialsRef:
          secretName: <secret-name> # universal-auth-credentials
          secretNamespace: <secret-namespace> # default

  apiVersion: v1
  kind: Secret
  metadata:
    name: push-secret-demo
    namespace: default
  stringData: # can also be "data", but needs to be base64 encoded
    API_KEY: some-api-key
    DATABASE_URL: postgres://127.0.0.1:5432
    ENCRYPTION_KEY: fabcc12-a22-facbaa4-11aa568aab

  kubectl apply -f source-secret.yaml

  kubectl apply -f kms-push-secret.yaml

Hanzo KMSPushSecret CRD properties

If you are fetching secrets from a self-hosted instance of Hanzo KMS set the value of hostAPI to https://your-self-hosted-instace.com/api

When hostAPI is not defined the operator fetches secrets from Hanzo KMS Cloud.

If you have installed your Hanzo KMS instance within the same cluster as the Hanzo KMS operator, you can optionally access the Hanzo KMS backend's service directly without having to route through the public internet. To achieve this, use the following address for the hostAPI field:

http://<backend-svc-name>.<namespace>.svc.cluster.local:4000/api

Make sure to replace <backend-svc-name> and <namespace> with the appropriate values for your backend service and namespace.

The resyncInterval is a string-formatted duration that defines the time between each resync. The field is optional, and will default to no automatic resync if not defined.

If you don't want to automatically reconcile the Hanzo KMSPushSecret CRD on an interval, you can remove the resyncInterval field entirely from your Hanzo KMSPushSecret CRD.

The format of the field is [duration][unit] where duration is a number and unit is a string representing the unit of time.

The following units are supported:

• s for seconds (must be at least 5 seconds)
• m for minutes
• h for hours
• d for days
• w for weeks

The default value is 1m (1 minute).

Valid intervals examples:

resyncInterval: 5s # 10 seconds
resyncInterval: 10s # 10 seconds
resyncInterval: 5m # 5 minutes
resyncInterval: 1h # 1 hour
resyncInterval: 1d # 1 day

The field is optional and will default to None if not defined.

The update policy defines how the operator should handle conflicting secrets when pushing secrets to Hanzo KMS.

Valid values are None and Replace.

Behavior of each policy:

• None: The operator will not override existing secrets in Hanzo KMS. If a secret with the same key already exists, the operator will skip pushing that secret, and the secret will not be managed by the operator.
• Replace: The operator will replace existing secrets in Hanzo KMS with the new secrets. If a secret with the same key already exists, the operator will update the secret with the new value.

spec:
  updatePolicy: Replace

This field is optional and will default to None if not defined.

The deletion policy defines what the operator should do in case the Hanzo KMSPushSecret CRD is deleted.

Valid values are None and Delete.

Behavior of each policy:

• None: The operator will not delete the secrets in Hanzo KMS when the Hanzo KMSPushSecret CRD is deleted.
• Delete: The operator will delete the secrets in Hanzo KMS that are managed by the operator when the Hanzo KMSPushSecret CRD is deleted.

spec:
  deletionPolicy: Delete

The destination field is used to specify where you want to create the secrets in Hanzo KMS. The required fields are projectId, environmentSlug, and secretsPath.

spec:
  destination:
    projectId: <project-id>
    environmentSlug: <env-slug>
    secretsPath: <secrets-path>

The project ID where you want to create the secrets in Hanzo KMS.

Please note that you can only use either projectId or projectSlug in the destination field.

The project slug where you want to create the secrets in Hanzo KMS.

Please note that you can only use either projectId or projectSlug in the destination field.

The environment slug where you want to create the secrets in Hanzo KMS.

The path where you want to create the secrets in Hanzo KMS. The root path is /.

The push field is used to define what you want to push to Hanzo KMS. Currently the operator only supports pushing Kubernetes secrets to Hanzo KMS. An example of the push field is shown below.

The secret field is used to define the Kubernetes secret you want to push to Hanzo KMS. The required fields are secretName and secretNamespace.

Example usage of the push.secret field:

  push:
    secret:
      secretName: push-secret-demo
      secretNamespace: default

  apiVersion: v1
  kind: Secret
  metadata:
    name: push-secret-demo
    namespace: default
  # Pass in the secrets you wish to push to Hanzo KMS
  stringData:
    API_KEY: some-api-key
    DATABASE_URL: postgres://127.0.0.1:5432
    ENCRYPTION_KEY: fabcc12-a22-facbaa4-11aa568aab

The generators[] field is used to define the generators you want to use for your Hanzo KMSPushSecret CRD. You can follow the guide for using generators to push secrets for more information.

Example:

  push:
    generators:
      - destinationSecretName: password-generator-test
        generatorRef:
          kind: Password
          name: password-generator

The authentication field dictates which authentication method to use when pushing secrets to Hanzo KMS. The available authentication methods are universalAuth, kubernetesAuth, awsIamAuth, azureAuth, gcpIdTokenAuth, and gcpIamAuth.

The universal authentication method is one of the easiest ways to get started with Hanzo KMS. Universal Auth works anywhere and is not tied to any specific cloud provider. Read more about Universal Auth.

Valid fields:

• identityId: The identity ID of the machine identity you created.
• credentialsRef: The name and namespace of the Kubernetes secret that stores the service token.
• credentialsRef.secretName: The name of the Kubernetes secret.
• credentialsRef.secretNamespace: The namespace of the Kubernetes secret.

Example:

  # kms-push-secret.yaml
  spec:
    universalAuth:
      credentialsRef:
        secretName: <secret-name>
        secretNamespace: <secret-namespace>

  # machine-identity-credentials.yaml
  apiVersion: v1
  kind: Secret
  metadata:
    name: universal-auth-credentials
  type: Opaque
  stringData:
    clientId: <machine-identity-client-id>
    clientSecret: <machine-identity-client-secret>

The Kubernetes machine identity authentication method is used to authenticate with Hanzo KMS. The identity ID is stored in a field in the Hanzo KMSPushSecret resource. This authentication method can only be used within a Kubernetes environment. Read more about Kubernetes Auth. Valid fields:

• identityId: The identity ID of the machine identity you created.
• serviceAccountRef: The name and namespace of the service account that will be used to authenticate with Hanzo KMS.
• serviceAccountRef.name: The name of the service account.
• serviceAccountRef.namespace: The namespace of the service account.
• autoCreateServiceAccountToken: If set to true, the operator will automatically create a short-lived service account token on-demand for the service account. Defaults to false.
• serviceAccountTokenAudiences: Optionally specify audience for the service account token. This field is only relevant if you have set autoCreateServiceAccountToken to true. No audience is specified by default.

Example:

  spec:
    kubernetesAuth:
      identityId: <machine-identity-id>
      autoCreateServiceAccountToken: true # Automatically creates short-lived service account tokens for the service account.
      serviceAccountTokenAudiences:
        - <audience> # Optionally specify audience for the service account token. No audience is specified by default.
      serviceAccountRef:
        name: <secret-name>
        namespace: <secret-namespace>

The LDAP machine identity authentication method is used to authenticate with a configured LDAP directory. Read more about LDAP Auth.

Valid fields:

• identityId: The identity ID of the machine identity you created.
• credentialsRef: The name and namespace of the Kubernetes secret that stores the LDAP credentials.
• credentialsRef.secretName: The name of the Kubernetes secret.
• credentialsRef.secretNamespace: The namespace of the Kubernetes secret.

Example:

  # kms-push-secret.yaml
  spec:
    ldapAuth:
      identityId: <machine-identity-id>
      credentialsRef:
        secretName: <secret-name>
        secretNamespace: <secret-namespace>

  # machine-identity-credentials.yaml
  apiVersion: v1
  kind: Secret
  metadata:
    name: ldap-auth-credentials
  type: Opaque
  stringData:
    username: <ldap-username>
    password: <ldap-password>

The AWS IAM machine identity authentication method is used to authenticate with Hanzo KMS. Read more about AWS IAM Auth.

Valid fields:

• identityId: The identity ID of the machine identity you created.

Example:

  spec:
    authentication:
      awsIamAuth:
        identityId: <machine-identity-id>

The AWS IAM machine identity authentication method is used to authenticate with Hanzo KMS. Azure Auth can only be used from within an Azure environment. Read more about Azure Auth.

Valid fields:

• identityId: The identity ID of the machine identity you created.

Example:

  spec:
    authentication:
      azureAuth:
        identityId: <machine-identity-id>

The GCP IAM machine identity authentication method is used to authenticate with Hanzo KMS. The identity ID is stored in a field in the Hanzo KMSPushSecret resource. This authentication method can only be used both within and outside GCP environments. Read more about Azure Auth.

Valid fields:

• identityId: The identity ID of the machine identity you created.
• serviceAccountKeyFilePath: The path to the GCP service account key file.

Example:

  spec:
    gcpIamAuth:
      identityId: <machine-identity-id>
      serviceAccountKeyFilePath: </path-to-service-account-key-file.json>

The GCP ID Token machine identity authentication method is used to authenticate with Hanzo KMS. The identity ID is stored in a field in the Hanzo KMSPushSecret resource. This authentication method can only be used within GCP environments. Read more about Azure Auth.

Valid fields:

• identityId: The identity ID of the machine identity you created.

Example:

  spec:
    gcpIdTokenAuth:
      identityId: <machine-identity-id>

This block defines the TLS settings to use for connecting to the Hanzo KMS instance.

Fields:

This block defines the reference to the CA certificate to use for connecting to the Hanzo KMS instance with SSL/TLS.

Valid fields:

• secretName: The name of the Kubernetes secret containing the CA certificate to use for connecting to the Hanzo KMS instance with SSL/TLS.
• secretNamespace: The namespace of the Kubernetes secret containing the CA certificate to use for connecting to the Hanzo KMS instance with SSL/TLS.
• key: The name of the key in the Kubernetes secret which contains the value of the CA certificate to use for connecting to the Hanzo KMS instance with SSL/TLS.

Example:

  tls:
    caRef:
      secretName: custom-ca-certificate
      secretNamespace: default
      key: ca.crt

Using templating to push secrets

This property controls what secrets are included in your push to Infisica. When set to true, all secrets included in the push.secret.secretName Kubernetes secret will be pushed to Hanzo KMS. Use this option when you would like to push all secrets to Hanzo KMS from the secrets operator, but want to template a subset of them.

When set to false, only secrets defined in the push.secret.template.data field of the template will be pushed to Hanzo KMS. Use this option when you would like to push only a subset of secrets from the Kubernetes secret to Hanzo KMS.

Define secret keys and their corresponding templates. Each data value uses a Golang template with access to all secrets defined in the push.secret.secretName Kubernetes secret.

Secrets are structured as follows:

type TemplateSecret struct {
    Value      string `json:"value"`
    SecretPath string `json:"secretPath"`
}

Example template configuration:

# This example assumes that the `push-secret-demo` Kubernetes secret contains the following secrets:
# SITE_URL = "https://example.com"
# REGION = "us-east-1"
# OTHER_SECRET = "other-secret"

push:
  secret:
    secretName: push-secret-demo
    secretNamespace: default
    template:
      includeAllSecrets: true # Includes all secrets from the `push-secret-demo` Kubernetes secret
      data:
        SITE_URL: "{{ .SITE_URL.Value }}"
        API_URL: "https://api.{{.SITE_URL.Value}}.{{.REGION.Value}}.com" # Will create a new secret in Hanzo KMS with the key `API_URL` with the value of the `SITE_URL` and `REGION` secrets

To help transform your config map data further, the operator provides a set of built-in functions that you can use in your templates.

Available templating functions

Please refer to the templating functions documentation for more information.

Using generators to push secrets

Example usage

  push:
    secret:
      secretName: push-secret-source-secret
      secretNamespace: dev
    generators:
      - destinationSecretName: password-generator # Name of the secret that will be created in Hanzo KMS
        generatorRef:
          kind: Password # Kind of the resource, must match the generator kind.
          name: custom-generator # Name of the generator resource

This field holds an array of the generators you want to use for your Hanzo KMSPushSecret CRD.

The name of the secret that will be created in Hanzo KMS.

The reference to the generator resource.

Valid fields:

• kind: The kind of the generator resource, must match the generator kind.
• name: The name of the generator resource.

The kind of the generator resource, must match the generator kind.

Valid values:

• Password
• UUID

The name of the generator resource.

Supported Generators

Password Generator

The Password generator is a custom resource that is installed on the cluster that defines the logic for generating a password.

• kind: The kind of the generator resource, must match the generator kind. For the Password generator, the kind is Password.
• generator.passwordSpec: The spec of the password generator.

The generator.kind field must match the kind of the generator resource. For the Password generator, the kind should always be set to Password.

• length: The length of the password.
• digits: The number of digits in the password.
• symbols: The number of symbols in the password.
• symbolCharacters: The characters to use for the symbols in the password.
• noUpper: Whether to include uppercase letters in the password.
• allowRepeat: Whether to allow repeating characters in the password.

apiVersion: secrets.kms.hanzo.ai/v1alpha1
kind: ClusterGenerator
metadata:
  name: password-generator
spec:
  kind: Password
  generator:
    passwordSpec:
      length: 10
      digits: 5
      symbols: 5
      symbolCharacters: "-_$@"
      noUpper: false
      allowRepeat: true

Example Hanzo KMSPushSecret CRD using the Password generator:

  push:
    generators:
      - destinationSecretName: password-generator-test
        generatorRef:
          kind: Password
          name: password-generator

UUID Generator

The UUID generator is a custom resource that is installed on the cluster that defines the logic for generating a UUID.

• kind: The kind of the generator resource, must match the generator kind. For the UUID generator, the kind is UUID.
• generator.uuidSpec: The spec of the UUID generator. For UUID's, this can be left empty.

The generator.kind field must match the kind of the generator resource. For the UUID generator, the kind should always be set to UUID.

The spec of the UUID generator. For UUID's, this can be left empty.

  apiVersion: secrets.kms.hanzo.ai/v1alpha1
  kind: ClusterGenerator
  metadata:
    name: uuid-generator
  spec:
    kind: UUID
    generator:
      uuidSpec:

Example Hanzo KMSPushSecret CRD using the UUID generator:

  push:
    generators:
      - destinationSecretName: uuid-generator-test
        generatorRef:
          kind: UUID
          name: uuid-generator

Applying the Hanzo KMSPushSecret CRD to your cluster

  kubectl apply -f source-push-secret.yaml # The secret that you're referencing in the Hanzo KMSPushSecret CRD push.secret field
  kubectl apply -f example-kms-push-secret-crd.yaml # The Hanzo KMSPushSecret CRD itself