> For the complete documentation index, see [llms.txt](https://docs.keeper.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.keeper.io/keeperpam/secrets-manager/integrations/kubernetes-external-secrets-operator.md).

# Kubernetes External Secrets Operator

Synchronize Secrets from Keeper Secrets Manager with the K8s External Secrets Operator

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FTuTzLzBatbwf6hlcKEGt%2Fksm-externalsecrets-kubernetes.jpg?alt=media&#x26;token=16302139-00a4-4e61-8c25-8d24f83c911b" alt=""><figcaption></figcaption></figure>

## Overview

[External Secrets Operator](https://charts.external-secrets.io) injects secrets into Kubernetes by synchronizing them from various external APIs. This guide primarily focuses on the setup process for External Secrets, facilitating the synchronization of secrets from your Keeper Vault into Kubernetes.

The External Operator documentation can be found [at this link](https://external-secrets.io/latest/provider/keeper-security/).

## Features

* Seamless synchronization of secrets from Keeper Vault into Kubernetes via External Secrets.
* Real-time access to secrets from Keeper Vault across all pods.

## Prerequisites

Before proceeding with the setup, ensure you have the following:

* Keeper Secrets Manager (KSM) access (See the [Quick Start Guide](https://docs.keeper.io/keeperpam/secrets-manager/quick-start-guide.md) for more details)
  * Secrets Manager add-on enabled for your Keeper account
  * Membership in a Role with the Secrets Manager enforcement policy enabled
* A Keeper [Secrets Manager Application](https://docs.keeper.io/keeperpam/secrets-manager/about/terminology.md#application) with secrets shared to it
  * See the [Quick Start Guide](https://docs.keeper.io/pages/-MeRAVfQmDBzKQBC0f_c#2.-create-an-application) for instructions on creating an Application
  * Share a folder with the application. Read-only is enough to pull secrets; give the application "Can Edit" on the folder only if you will use PushSecret.
  * Add a Client Device to the application with IP lock disabled. Pods move between nodes and their outbound IP can change; an IP-locked device stops working when it does.
* An initialized Keeper [Secrets Manager Configuration](https://docs.keeper.io/keeperpam/secrets-manager/about/secrets-manager-configuration.md), exported as a Base64 string. A one-time access token (for example `US:abc123...`) does not work with External Secrets.
* The following commands installed:
  * [`helm`](https://helm.sh/) - package manager for Kubernetes
  * [`kubectl`](https://kubernetes.io/docs/reference/kubectl/) - command line tool for Kubernetes

## Setup

### Install External Secrets With Helm

To install External Secrets with Helm, run the following commands:

```shell
helm repo add external-secrets https://charts.external-secrets.io

helm install external-secrets \
    external-secrets/external-secrets \
    -n external-secrets \
    --create-namespace
```

### Create Kubernetes Secret to store Base64 KSM Config

After creating a [Secrets Manager Configuration](https://docs.keeper.io/keeperpam/secrets-manager/about/secrets-manager-configuration.md) for your device, you will have a Base64 JSON string that contains connection tokens, encryption keys, identifiers and domain information used to authenticate and decrypt data from the Keeper Secrets Manager APIs.

The Base64 JSON config string will be set by External Secrets to authenticate against Keeper Security and defined in a regular Kubernetes Secret.

Invoking the following command will create a Kubernetes Secret which is used to authenticate to Keeper Secrets Manager:

{% code lineNumbers="true" %}

```yaml
kubectl apply -f - <<EOF
apiVersion: v1
kind: Secret
metadata:
  name: ksm-config-secret # name of the k8s Secret where KSM config is stored
type: Opaque
data:
  ksm_config: "[REPLACE WITH YOUR BASE64 JSON string]"
EOF
```

{% endcode %}

**Note:** Lines 2-8 in the above code snippet can be stored in a YAML file and applied with the command `kubectl apply`. For example, you can store lines 2-8 in `secrets.yaml` and execute the following:

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

### Create SecretStore

After creating a Kubernetes Secret with `ksm_config` defined to your Base64 JSON string, you can now create your SecretStore.

Invoking the following command will create your SecretStore:

<pre class="language-yaml" data-line-numbers data-full-width="false"><code class="lang-yaml"><strong>kubectl apply -f - &#x3C;&#x3C;EOF
</strong>apiVersion: external-secrets.io/v1 
kind: SecretStore
metadata:
<strong>  name: my-external-secrets-secretstore   # name of the SecretStore where retrieved secrets will be stored once fetched from Keeper Secrets Manager (KSM)
</strong>spec:
  provider:
    keepersecurity:                       # name of the SecretStore provider, in this case KeeperSecurity
<strong>      authRef:
</strong>        name: ksm-config-secret           # name of the k8s Secret where KSM config is stored
        key: ksm_config                   # key in the k8s Secret where KSM config is stored
      folderID: "[SHARED FOLDER UID]"     # UID of the shared folder in KeeperSecurity where the records 
                                          #   are stored. Make sure the folder is shared into the KSM Application
EOF
</code></pre>

{% hint style="info" %}
In the above code snippet, define `folderID` with the UID of the shared folder where the records are stored in your Vault
{% endhint %}

{% hint style="info" %}
In case of a `ClusterSecretStore`, Be sure to provide `namespace` for `SecretAccessKeyRef` with the namespace of the secret that we just created.
{% endhint %}

**Note:** Lines 2-13 in the above code snippet can be stored in a YAML file and applied with the command `kubectl apply`. For example, you can store lines 2-13 in `secretstore.yaml` and execute the following:

```bash
kubectl apply -f secretstore.yaml
```

### Create ExternalSecret

Next, you need to create your ExternalSecret.

The following code snippet will create your External Secret and store the values of the login & password field for the specified record into the Kubernetes Secret. These fields are defined in the `target.template.data` section and refreshed every every hour. For a full list of supported fields, visit this [page](https://docs.keeper.io/keeperpam/secrets-manager/about/field-record-types.md).

{% code lineNumbers="true" fullWidth="false" %}

```yaml
kubectl apply -f - <<EOF
apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
 name: ksm-external-secret
spec:
 refreshInterval: 1h               # how often External Secrets re-reads the record from Keeper.
                                    #   Changes made in Keeper reach Kubernetes within this interval.
                                    #   Every refresh is a request to Keeper, so avoid very short values at scale.
 secretStoreRef:                    # reference to the SecretStore defined above to authenticate against Keeper Security
   kind: SecretStore                # tells External Secrets the type of the secret store, should be same as the one defined above
   name: my-external-secrets-secretstore  

 dataFrom:                          # tells External Secrets which record to use to fetch from Keeper Secrets Manager (KSM)
   - extract:
       key: "[RECORD UID]"          # UID of the record in Keeper where the secrets are going to be fetched from
 target:                            # tells External Secrets the target location where to store the secrets once fetched from Keeper Security
   name: my-external-secrets-values # name of the k8s Secret to be created
   creationPolicy: Owner            # tells External Secrets to create the k8s Secret if it doesn't exist
   template:
     engineVersion: v2          
     data:
       username: "{{ .login }}"     # tells External Secrets to store the value of 
                                    # the login field in Keeper Security into the k8s Secret under the key username
       password: "{{ .password }}"  # tells External Secrets to store the value of 
                                    # the password field in Keeper Security into the k8s Secret under the key password
EOF
```

{% endcode %}

{% hint style="info" %}
In the above code snippet, replace "\[RECORD UID]" with the UID of your desired record
{% endhint %}

{% hint style="info" %}
For complex [types](https://docs.keeper.io/keeperpam/secrets-manager/about/field-record-types.md), like `name`, `phone`, `bankAccount`, which does not match with a single string value, external secrets will return the complete JSON string. Use the JSON template functions to decode.
{% endhint %}

**Note:** Lines 2-27 in the above code snippet can be stored in a YAML file and applied with the command `kubectl apply`. For example, you can store lines 2-27 in `externalsecret.yaml` and execute the following:

```bash
kubectl apply -f externalsecret.yaml
```

#### Behavior <a href="#behavior" id="behavior"></a>

* How a Record is equated to an ExternalSecret:
  * `remoteRef.key` is equated to a Record's UID. To use the record's title instead, set `getByTitleFallback: true` on the SecretStore (titles must be unique among the records the application can see).
  * `remoteRef.property` is equated to one of the following options:
    * Fields: the field's Label if it has one, otherwise the [Record's field's Type](https://docs.keeper.io/keeperpam/secrets-manager/about/field-record-types.md) (for example login, password, url)
    * CustomFields: Record's field's Label
    * Files: the attachment's name as shown in the vault (the file's title). If the attachment was renamed in the vault, use the new name; the original filename will not match.
    * If empty, defaults to the complete Record in JSON format
  * `remoteRef.version` is currently not supported.
* `dataFrom`:
  * `find.path` is currently not supported.
  * `find.name.regexp` is matched against the record's Title. Each matching record becomes one key, named after the title (characters that are not allowed in a Kubernetes Secret key become "\_"), containing the complete record in JSON format.
  * `find.tags` are not supported at this time.

#### Custom Fields and Files

Custom fields and file attachments need no JSON parsing: set `property` to the custom field's label, or to the attachment's name as shown in the vault.

```yaml
kubectl apply -f - <<EOF
apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: ksm-custom-and-files
spec:
  refreshInterval: 1h
  secretStoreRef:
    kind: SecretStore
    name: my-external-secrets-secretstore
  target:
    name: my-app-extras                # Kubernetes Secret to create
  data:
    - secretKey: api-key               # key in the Kubernetes Secret
      remoteRef:
        key: "[RECORD UID]"
        property: "api_key"            # custom field: its label
    - secretKey: app-file
      remoteRef:
        key: "[RECORD UID]"
        property: "config.json"        # attachment: its name as shown in the vault
EOF
```

A pod can then read the custom field as an environment variable and the attachment as a file:

```yaml
      env:
        - name: API_KEY
          valueFrom:
            secretKeyRef:
              name: my-app-extras
              key: api-key
      volumeMounts:
        - name: keeper-files
          mountPath: /etc/keeper       # the attachment appears as /etc/keeper/app-file
          readOnly: true
  volumes:
    - name: keeper-files
      secret:
        secretName: my-app-extras
        items:
          - key: app-file
            path: app-file
```

Binary attachments (keystores, DER certificates) are copied byte for byte. To take every field, custom field and attachment of a record at once, use `dataFrom: - extract: key: "[RECORD UID]"`; characters not allowed in Kubernetes Secret keys, such as spaces, become "\_", and an extra `fileRef` key holding Keeper's internal attachment IDs can be ignored.

### Limitations <a href="#limitations" id="limitations"></a>

There are some limitations using this provider.

* Keeper Secret Manager does not work with legacy non-typed records
* Using tags `find.tags` is not supported by KSM
* Using path `find.path` is not supported at the moment
* Every field label, custom field label and attachment name in a record must be unique, including the names of standard fields such as login, password and url. If two collide (for example a custom field labelled "password" on a login record, or two attachments with the same name), the whole record fails with "invalid Secret. Following keys are duplicated", even for fields you did not ask for. Rename one of them in the vault.

### Push Secrets

Push Secret creates and updates records of the record type `externalSecrets`

Behavior

* `selector`:
* `secret.name`: name of the kubernetes secret to be pushed
* `data.match`:
* `secretKey`: key on the selected secret to be pushed
* `remoteRef.remoteKey`: Secret and key to be created on the remote provider
  * Format: SecretName/SecretKey

### Create PushSecret

To create a Keeper Security record from Kubernetes a `Kind=PushSecret` is needed.

<pre class="language-yaml" data-line-numbers data-full-width="false"><code class="lang-yaml"><strong>kubectl apply -f - &#x3C;&#x3C;EOF
</strong>apiVersion: external-secrets.io/v1alpha1
kind: PushSecret
metadata:
  name: example
spec:
  secretStoreRefs:
    - name: my-external-secrets-secretstore
      kind: SecretStore
  refreshInterval: "1h"
  deletionPolicy: Delete
  selector:
    secret:
      name: secret-name # k8s secret to be pushed
  data:
    - match:
        secretKey: secret-key # k8s key within the secret to be pushed
        remoteRef:
          remoteKey: remote-secret-name/remote-secret-key # This will create a record called "remote-secret-name" with a key "remote-secret-key"
EOF
</code></pre>

**Note:** Lines 2-19 in the above code snippet can be stored in a YAML file and applied with the command `kubectl apply`. For example, you can store lines 2-19 in `pushsecret.yaml` and execute the following:

```bash
kubectl apply -f pushsecret.yaml
```

{% hint style="warning" %}
Make sure there's only one record with the title `remote-secret-name` in the KSM Application in use.
{% endhint %}

#### Limitations <a href="#limitations_1" id="limitations_1"></a>

* External Secrets writes one field when it creates a record, and afterwards can only update fields that already exist on it. Pushing several keys into the same new record therefore does not work:
  * for `login`/`username`, `password` and `url` keys, the second key is skipped without an error and the PushSecret still shows Synced;
  * for any other key, the PushSecret fails with "does not contain any custom field with label ".
* To push several values, either push each one to its own record, or create the record first (type `externalSecrets`, with every field you will push) so External Secrets only updates it.
* Changing the Kubernetes Secret is pushed on the next `refreshInterval`. To push right away: `kubectl annotate pushsecret <name> force-sync=$(date +%s) --overwrite`
* With `deletionPolicy: Delete`, deleting the PushSecret also deletes the record in Keeper.

### Troubleshooting

* A SecretStore that shows STATUS Valid is only well formed; the connection to Keeper is not checked until an ExternalSecret syncs. An invalid KSM configuration (or a one-time token instead of a configuration) still shows Valid.
* If an ExternalSecret has no status, or shows SecretSyncedError, the event usually just says "could not get secret data from provider". The real reason — for example "no record matched \[record UID]" or "does not have any key matching \[field name]" — is in the operator log:

```bash
kubectl logs -n external-secrets deploy/external-secrets | grep <externalsecret-name>
```

* To retry right away instead of waiting for refreshInterval:

```bash
kubectl annotate externalsecret <name> force-sync=$(date +%s) --overwrite
```

* Delete ExternalSecret and PushSecret objects before uninstalling External Secrets. Otherwise their namespaces stay in Terminating.

## Verifying Setup

After setting up your [Kubernetes Secret](#create-kubernetes-secret-to-store-base64-ksm-config), [SecretStore](#create-secretstore), and [ExternalSecret](#create-externalsecret), you can extract secrets with the command `kubectl get secrets`

In the above code snippets, the name of the secret is my-external-secrets-values and we store the following record values:

```yaml
data:
       username: "{{ .login }}"                                      
       password: "{{ .password }}"
```

To get the login and password values, invoke the following command:

```
$ kubectl get secret my-external-secrets-values -o jsonpath="{.data}"
{"password":"a2lsbCB5b3U=","username":"SSB3aWxs"}
```

The above response is encoded, to decode, invoke the following:

{% code fullWidth="false" %}

```
$ kubectl get secret my-external-secrets-values -o jsonpath="{.data.password}" | base64 --decode
pAs$w0rd
```

{% endcode %}

## Conclusion

In conclusion, this guide has detailed a step-by-step process for integrating the Keeper Secrets Manager with Kubernetes via the Kubernetes External Secrets Operator. By following these steps, you'll be able to seamlessly synchronize your secrets stored in Keeper Vault into your Kubernetes environment. This not only provides a secure method to manage your secrets but also facilitates real-time access across all your pods.

The processes outlined, including setting up the External Secrets operator, creating a Kubernetes Secret, SecretStore, and ExternalSecret, are key to this integration. Upon successful setup, the provided commands allow you to verify the integration and retrieve stored secrets effortlessly.

The integration of Keeper Secrets Manager with Kubernetes enhances the security infrastructure of your applications running in the Kubernetes environment. It provides a solid foundation for managing your secrets, thereby improving overall operational efficiency and security posture.

Remember to replace all placeholders in the command snippets with your specific information, and don't hesitate to refer back to this guide anytime you need to set up or manage your External Secrets in Kubernetes.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.keeper.io/keeperpam/secrets-manager/integrations/kubernetes-external-secrets-operator.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
