kms/docs/integrations/platforms/kubernetes/kms-push-secret-crd.mdx

---
sidebarTitle: "KmsPushSecret CRD"
title: "Using the KmsPushSecret CRD"
description: "Learn how to use the KmsPushSecret CRD to push and manage secrets in KMS."
---


## Overview

The **KmsPushSecret** CRD allows you to create secrets in your Kubernetes cluster and push them to KMS.


This CRD offers the following features:
- **Push Secrets** from a Kubernetes secret into KMS.
- **Manage secret lifecycle** of pushed secrets in KMS. When the Kubernetes secret is updated, the operator will automatically update the secrets in KMS. Optionally, when the Kubernetes secret is deleted, the operator will delete the secrets in KMS automatically.

### Prerequisites

- A project within KMS.
- A [machine identity](/documentation/platform/identities/machine-identities) ready for use in KMS that has permissions to create secrets in your project.
- The operator is installed on to your Kubernetes cluster.

## Example usage

Below is a sample KmsPushSecret CRD that pushes secrets defined in a Kubernetes secret to KMS.

After filling out the fields in the KmsPushSecret CRD, you can apply it directly to your cluster.

Before applying the KmsPushSecret CRD, you need to create a Kubernetes secret containing the secrets you want to push to KMS. An example can be seen below the KmsPushSecret CRD.

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

    # Optional, defaults to no replacement.
    updatePolicy: Replace # If set to replace, existing secrets inside 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 KMS managed by the operator, will be deleted if the 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
```

```yaml source-secret.yaml
  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
```

```bash
  kubectl apply -f source-secret.yaml
```

After applying the soruce-secret.yaml file, you are ready to apply the KmsPushSecret CRD.

```bash
  kubectl apply -f kms-push-secret.yaml
```

After applying the KmsPushSecret CRD, you should notice that the secrets you have defined in your source-secret.yaml file have been pushed to your specified destination in KMS.


## KmsPushSecret CRD properties

<Accordion title="hostAPI">
  If you are fetching secrets from a self-hosted instance of KMS set the value of `hostAPI` to
  `https://your-self-hosted-instace.com/api`

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

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

    ``` bash
    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.

  </Accordion>
</Accordion>

<Accordion title="resyncInterval">

  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 KmsPushSecret CRD on an interval, you can remove the `resyncInterval` field entirely from your 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:
  ```yaml
  resyncInterval: 5s # 10 seconds
  resyncInterval: 10s # 10 seconds
  resyncInterval: 5m # 5 minutes
  resyncInterval: 1h # 1 hour
  resyncInterval: 1d # 1 day
  ```
</Accordion>

<Accordion title="updatePolicy">

  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 KMS.

  Valid values are `None` and `Replace`.

  Behavior of each policy:
  - `None`: The operator will not override existing secrets in 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 KMS with the new secrets. If a secret with the same key already exists, the operator will update the secret with the new value.

  ```yaml
  spec:
    updatePolicy: Replace
  ```
</Accordion>

<Accordion title="deletionPolicy">

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

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

  Valid values are `None` and `Delete`.

  Behavior of each policy:
  - `None`: The operator will not delete the secrets in KMS when the KmsPushSecret CRD is deleted.
  - `Delete`: The operator will delete the secrets in KMS that are managed by the operator when the KmsPushSecret CRD is deleted.

  ```yaml
  spec:
    deletionPolicy: Delete
  ```
</Accordion>

<Accordion title="destination">
  The `destination` field is used to specify where you want to create the secrets in KMS. The required fields are `projectId`, `environmentSlug`, and `secretsPath`.

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

  <Accordion title="destination.projectId">
    The project ID where you want to create the secrets in KMS.

    <Note>
      Please note that you can only use either `projectId` or `projectSlug` in the `destination` field.
    </Note>
  </Accordion>

  <Accordion title="destination.projectSlug">
    The project slug where you want to create the secrets in KMS.

    <Note>
      Please note that you can only use either `projectId` or `projectSlug` in the `destination` field.
    </Note>
  </Accordion>

  <Accordion title="destination.environmentSlug">
    The environment slug where you want to create the secrets in KMS.
  </Accordion>

  <Accordion title="destination.secretsPath">
    The path where you want to create the secrets in KMS. The root path is `/`.
  </Accordion>

</Accordion>

<Accordion title="push">
  The `push` field is used to define what you want to push to KMS. Currently the operator only supports pushing Kubernetes secrets to KMS. An example of the `push` field is shown below.



  <Accordion title="secret">
    The `secret` field is used to define the Kubernetes secret you want to push to KMS. The required fields are `secretName` and `secretNamespace`.



    Example usage of the `push.secret` field:

    ```yaml kms-push-secret.yaml
      push:
        secret:
          secretName: push-secret-demo
          secretNamespace: default
    ```

    ```yaml push-secret-demo.yaml
      apiVersion: v1
      kind: Secret
      metadata:
        name: push-secret-demo
        namespace: default
      # Pass in the secrets you wish to push to KMS
      stringData:
        API_KEY: some-api-key
        DATABASE_URL: postgres://127.0.0.1:5432
        ENCRYPTION_KEY: fabcc12-a22-facbaa4-11aa568aab
    ```
  </Accordion>
  <Accordion title="generators[]">
    The `generators[]` field is used to define the generators you want to use for your KmsPushSecret CRD.
    You can follow the guide for [using generators to push secrets](#using-generators-to-push-secrets) for more information.

    Example:

    ```yaml
      push:
        generators:
          - destinationSecretName: password-generator-test
            generatorRef:
              kind: Password
              name: password-generator
    ```
  </Accordion>
</Accordion>

<Accordion title="authentication">

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


  <Accordion title="universalAuth">
    The universal authentication method is one of the easiest ways to get started with KMS. Universal Auth works anywhere and is not tied to any specific cloud provider.
    [Read more about Universal Auth](/documentation/platform/identities/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:

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

    ```yaml
      # 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>
    ```

  </Accordion>
  <Accordion title="kubernetesAuth">
    The Kubernetes machine identity authentication method is used to authenticate with KMS. The identity ID is stored in a field in the KmsPushSecret resource. This authentication method can only be used within a Kubernetes environment.
    [Read more about Kubernetes Auth](/documentation/platform/identities/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 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:

    ```yaml
      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>
    ```
  </Accordion>
  <Accordion title="ldapAuth">
     The LDAP machine identity authentication method is used to authenticate with a configured LDAP directory. [Read more about LDAP Auth](/documentation/platform/identities/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:

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

     ```yaml
       # machine-identity-credentials.yaml
       apiVersion: v1
       kind: Secret
       metadata:
         name: ldap-auth-credentials
       type: Opaque
       stringData:
         username: <ldap-username>
         password: <ldap-password>
     ```
  </Accordion>
  <Accordion title="awsIamAuth">
    The AWS IAM machine identity authentication method is used to authenticate with KMS.
    [Read more about AWS IAM Auth](/documentation/platform/identities/aws-auth).

    Valid fields:
    - `identityId`: The identity ID of the machine identity you created.

    Example:

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

  </Accordion>
  <Accordion title="azureAuth">
    The AWS IAM machine identity authentication method is used to authenticate with KMS. Azure Auth can only be used from within an Azure environment.
    [Read more about Azure Auth](/documentation/platform/identities/azure-auth).

    Valid fields:
    - `identityId`: The identity ID of the machine identity you created.

    Example:

    ```yaml
      spec:
        authentication:
          azureAuth:
            identityId: <machine-identity-id>
    ```
  </Accordion>
  <Accordion title="gcpIamAuth">
    The GCP IAM machine identity authentication method is used to authenticate with KMS. The identity ID is stored in a field in the KmsPushSecret resource. This authentication method can only be used both within and outside GCP environments.
    [Read more about Azure Auth](/documentation/platform/identities/gcp-auth).


    Valid fields:
    - `identityId`: The identity ID of the machine identity you created.
    - `serviceAccountKeyFilePath`: The path to the GCP service account key file.

    Example:

    ```yaml
      spec:
        gcpIamAuth:
          identityId: <machine-identity-id>
          serviceAccountKeyFilePath: </path-to-service-account-key-file.json>
    ```
  </Accordion>
  <Accordion title="gcpIdTokenAuth">
    The GCP ID Token machine identity authentication method is used to authenticate with KMS. The identity ID is stored in a field in the KmsPushSecret resource. This authentication method can only be used within GCP environments.
    [Read more about Azure Auth](/documentation/platform/identities/gcp-auth).

    Valid fields:
    - `identityId`: The identity ID of the machine identity you created.

    Example:

    ```yaml
      spec:
        gcpIdTokenAuth:
          identityId: <machine-identity-id>
    ```
  </Accordion>

</Accordion>


<Accordion title="tls">
  This block defines the TLS settings to use for connecting to the KMS
  instance.

  Fields:
  <Accordion title="caRef">
    This block defines the reference to the CA certificate to use for connecting to the KMS instance with SSL/TLS.

    Valid fields:
    - `secretName`: The name of the Kubernetes secret containing the CA certificate to use for connecting to the KMS instance with SSL/TLS.
    - `secretNamespace`: The namespace of the Kubernetes secret containing the CA certificate to use for connecting to the 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 KMS instance with SSL/TLS.

    Example:

    ```yaml
      tls:
        caRef:
          secretName: custom-ca-certificate
          secretNamespace: default
          key: ca.crt
    ```
  </Accordion>

</Accordion>


## Using templating to push secrets

Pushing secrets to KMS from the operator may not always be enough.
Templating is a useful utility of the KMS secrets operator that allows you to use Go Templating to template the secrets you want to push to KMS.
Using Go templates, you can format, combine, and create new key-value pairs of secrets that you want to push to KMS.

<Accordion title="push.secret.template"/>
<Accordion title="push.secret.template.includeAllSecrets">
  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 KMS.
  **Use this option when you would like to push all secrets to 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 KMS.
  Use this option when you would like to push **only** a subset of secrets from the Kubernetes secret to KMS.
</Accordion>
<Accordion title="push.secret.template.data">
  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:

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

  #### Example template configuration:

  ```yaml
  # 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 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](/integrations/platforms/kubernetes/overview#available-helper-functions) for more information.
</Accordion>

## Using generators to push secrets

Generators allow secrets to be dynamically generated during each reconciliation cycle and then pushed to KMS. They are useful for use cases where a new secret value is needed on every sync, such as ephemeral credentials or one-time-use tokens.

A generator is defined as a custom resource (`ClusterGenerator`) within the cluster, which specifies the logic for generating secret values. Generators are stateless, each invocation triggers the creation of a new set of values, with no tracking or persistence of previously generated data.

Because of this behavior, you may want to disable automatic syncing for the `KmsPushSecret` resource to avoid continuous regeneration of secrets. This can be done by omitting the `resyncInterval` field from the KmsPushSecret CRD.

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

To use a generator, you must specify at least one generator in the `push.generators[]` field.


<Accordion title="push.generators[]">
  This field holds an array of the generators you want to use for your KmsPushSecret CRD.
</Accordion>

<Accordion title="push.generators[].destinationSecretName">
  The name of the secret that will be created in KMS.
</Accordion>

<Accordion title="push.generators[].generatorRef">
  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.
</Accordion>

<Accordion title="push.generators[].generatorRef.kind">
  The kind of the generator resource, must match the generator kind.

  Valid values:
  - `Password`
  - `UUID`
</Accordion>

<Accordion title="push.generators[].generatorRef.name">
  The name of the generator resource.
</Accordion>

### Supported Generators
Below are the currently supported generators for the KmsPushSecret CRD. Each generator is a `ClusterGenerator` custom resource that can be used to customize the generated secret.

<Accordion title="Password Generator">
  ### 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.

    <Accordion title="generator.kind">
    The `generator.kind` field must match the kind of the generator resource. For the Password generator, the kind should always be set to  `Password`.
    </Accordion>
    <Accordion title="generator.passwordSpec">
    - `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.
    </Accordion>

  ```yaml password-cluster-generator.yaml
  apiVersion: secrets.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 KmsPushSecret CRD using the Password generator:
  ```yaml kms-push-secret-crd.yaml
    push:
      generators:
        - destinationSecretName: password-generator-test
          generatorRef:
            kind: Password
            name: password-generator
  ```
</Accordion>
<Accordion title="UUID 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.

  <Accordion title="generator.kind">
    The `generator.kind` field must match the kind of the generator resource. For the UUID generator, the kind should always be set to  `UUID`.
  </Accordion>

  <Accordion title="generator.uuidSpec">
    The spec of the UUID generator. For UUID's, this can be left empty.
  </Accordion>

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

  Example KmsPushSecret CRD using the UUID generator:

  ```yaml kms-push-secret-crd.yaml
    push:
      generators:
        - destinationSecretName: uuid-generator-test
          generatorRef:
            kind: UUID
            name: uuid-generator
  ```
</Accordion>




## Applying the KmsPushSecret CRD to your cluster

Once you have configured the `KmsPushSecret` CRD with the required fields, you can apply it to your cluster.
After applying, you should notice that the secrets have been pushed to KMS.

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