> ## Documentation Index
> Fetch the complete documentation index at: https://www.1password.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Kubernetes Operator

export const YouTubeVideo = ({src, title, alt}) => {
  return <Frame>
      <iframe className="w-full aspect-video rounded-xl" src={src} title={alt ?? title} allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen></iframe>
    </Frame>;
};

The 1Password Connect Kubernetes Operator integrates [Kubernetes Secrets <Icon icon="arrow-up-right-from-square" />](https://kubernetes.io/docs/concepts/configuration/secret/) with 1Password with one or more Connect servers. It allows you to:

* Create Kubernetes Secrets from 1Password items and load them into Kubernetes deployments.
* Automatically restart deployments when 1Password items update.

<YouTubeVideo src="https://www.youtube.com/embed/kxbfCsJARHM" title="Using 1Password Connect with Kubernetes Operator" />

## Requirements

Before using the Kubernetes Operator, make sure you finish the requirement steps. The requirements vary slightly depending on how you plan to deploy the Kubernetes Operator.

<Tabs groupId="requirements" queryString="deployment-type">
  <Tab title="Deploy with Helm">
    Before you can deploy the Kubernetes Operator with the 1Password Connect and Operator Helm chart, you must:

    <ul>
      <li><a href="https://1password.com/pricing/password-manager">Sign up for 1Password</a>.</li>
      <li>Install <a href="/cli/get-started/">1Password CLI</a>.</li>
      <li>Have a Kubernetes deployment. You can also use <a href="https://minikube.sigs.k8s.io/docs/start/">minikube <Icon icon="arrow-up-right-from-square" /></a> to test locally.</li>
      <li>Install <a href="https://helm.sh/">Helm <Icon icon="arrow-up-right-from-square" /></a>.</li>
      <li>Create a Secrets Automation workflow as a <a href="/connect/get-started/#step-1">Connect server</a>. You need the Connect server's <code>1password-credentials.json</code> file.</li>
    </ul>
  </Tab>

  <Tab title="Deploy manually with Connect">
    Before you can deploy the Kubernetes Operator with a Kubernetes deployment specification file, you must:

    <ul>
      <li><a href="https://1password.com/pricing/password-manager">Sign up for 1Password</a>.</li>
      <li>Install <a href="/cli/get-started/">1Password CLI</a>.</li>
      <li>Have a Kubernetes deployment. You can also use <a href="https://minikube.sigs.k8s.io/docs/start/">minikube <Icon icon="arrow-up-right-from-square" /></a> to test locally.</li>
      <li>Create a Secrets Automation workflow as a <a href="/connect/get-started/#step-1">Connect server</a>. You need the Connect server's <code>1password-credentials.json</code> file.</li>
    </ul>
  </Tab>

  <Tab title="Deploy manually with a service account">
    Before you can deploy the Kubernetes Operator with a service account, you must:

    <ul>
      <li><a href="https://1password.com/pricing/password-manager">Sign up for 1Password</a>.</li>
      <li>Have a Kubernetes deployment. You can also use <a href="https://minikube.sigs.k8s.io/docs/start/">minikube <Icon icon="arrow-up-right-from-square" /></a> to test locally.</li>
    </ul>
  </Tab>
</Tabs>

## Limitations

The Kubernetes Operator supports Connect servers and service accounts.

Additionally, the Operator doesn't allow you to select secrets granularly or use multiple credentials simultaneously. For a complete comparison of features and functionality, see [Kubernetes integrations](/k8s/integrations/).

## Deployment

There are two ways to deploy the Kubernetes Operator:

1. Using the 1Password Connect and Operator Helm chart.
2. Manually using a Kubernetes deployment specification file.

<Warning>
  The recommended way to deploy the Kubernetes Operator is with Helm. Deploying manually is a much more involved and complicated process.
</Warning>

<Tabs groupId="deployment" queryString="deployment-type">
  <Tab title="Deploy with Helm">
    The following instructions cover deploying the Kubernetes Operator using the [1Password Connect and Operator Helm chart](/k8s/helm/).

    You can use the 1Password Connect and Operator Helm chart to deploy the Kubernetes alongside Connect or without Connect.

    ### Step 1. Add the 1Password Helm chart repository

    The following command adds the [1Password Helm chart repository <Icon icon="github" />](https://github.com/1Password/connect-helm-charts) to your local instance of Helm. This allows you to download and install all charts from 1Password's GitHub repository.

    ```shell theme={null}
    helm repo add 1password https://1password.github.io/connect-helm-charts/
    ```

    <h3 id="helm-step-2">
      Step 2. Install the Kubernetes Operator using Helm
    </h3>

    You can use the 1Password Connect and Operator Helm chart to deploy the Kubernetes Operator with Connect or without Connect.

    In most cases, it makes sense to deploy the Kubernetes Operator alongside Connect because it simplifies the setup and communication between Connect and the Operator. However, it might make more sense to deploy only the Kubernetes Operator if you already have a Connect deployment in production.

    <Tabs quertString="install" groupId="install">
      <Tab title="With Connect">
        To install the Kubernetes Operator with Connect, use the following command. It deploys the Kubernetes Operator with a 1Password Connect server using the `1password-credentials.json` file.

        ```shell theme={null}
        helm install connect 1password/connect --set-file connect.credentials=1password-credentials.json --set operator.create=true --set operator.token.value=OP_CONNECT_TOKEN
        ```

        If you don't already have a Connect token, use the following command instead. Make sure to replace `SERVER` and `VAULT` with the correct values.

        ```shell theme={null}
        helm install connect 1password/connect --set-file connect.credentials=1password-credentials.json --set operator.create=true --set operator.token.value=$(op connect token create --server SERVER --vault VAULT)
        ```
      </Tab>

      <Tab title="Without Connect">
        To install the Kubernetes Operator without Connect, set `operator.create` to `true` and `connect.create` to `false`.

        ```shell theme={null}
        helm install connect 1password/connect --set operator.create=true --set operator.token.value=<token> --set connect.create=false
        ```

        If you don't already have a Connect token, use the following command instead. Make sure to replace `SERVER` and `VAULT` with the correct values.

        ```shell theme={null}
        helm install connect 1password/connect --set operator.create=true --set operator.token.value=$(op connect token create --server SERVER --vault VAULT) --set connect.create=false
        ```
      </Tab>

      <Tab title="With a service account">
        To install the Kubernetes Operator with a service account, set `operator.create` to `true`, `connect.create` to `false`, and `operator.authMethod` to `service-account`.

        ```shell theme={null}
        helm install connect 1password/connect --set operator.create=true --set connect.create=false --set operator.authMethod=service-account --set operator.serviceAccountToken.value=<token>
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="Deploy manually with Connect">
    The following instructions cover deploying the Kubernetes Operator manually, using a [Kubernetes deployment specification <Icon icon="arrow-up-right-from-square" />](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/).

    1. [Create a deployment specification.](#manual-step-1)
    2. [Create a Kubernetes Secret from the Connect server credentials.](#manual-step-2)
    3. [Add the `MANAGE_CONNECT` environment variable.](#manual-step-3)
    4. [Create a Kubernetes Secret for the Connect server token.](#manual-step-4)
    5. [Deploy the Kubernetes Operator.](#manual-step-5)

    <h3 id="manual-step-1">
      Step 1: Create a deployment specification
    </h3>

    1. Create a [Kubernetes deployment specification <Icon icon="arrow-up-right-from-square" />](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) YAML file. You can use the example [`manager.yaml` <Icon icon="github" />](https://github.com/1Password/onepassword-operator/blob/main/config/manager/manager.yaml) file from the Kubernetes Operator repository on GitHub.

    You can also update an existing Kubernetes deployment specification to include the `1password/onepassword-operator` container image and options.

    <h3 id="manual-step-2">
      Step 2: Create a Kubernetes Secret from the Connect server credentials
    </h3>

    1. Encode the `1password-credentials.json` file you generated when you created your Connect server and name it `FILE_NAME`.

       ```shell theme={null}
       cat 1password-credentials.json | base64 | \  tr '/+' '_-' | tr -d '=' | tr -d '\n' > FILE_NAME
       ```

    2. Use `kubectl` to create a Kubernetes Secret from the encoded `FILE_NAME` file.

       ```shell theme={null}
       kubectl create secret generic op-credentials --from-file=FILE_NAME
       ```

    <h3 id="manual-step-3">
      Step 3: Add the `MANAGE_CONNECT` environment variable
    </h3>

    1. Add the `MANAGE_CONNECT` environment variable to the Kubernetes Operator container (`onepassword-connect-operator`) in the deployment specification file and set it to `true`.

    The `MANAGE_CONNECT` environment variable tells the Kubernetes Operator to automatically deploy a default configuration of the 1Password Connect server to the current namespace.

    ```yaml deployment-specification.yaml theme={null}
    - name: MANAGE_CONNECT
      value: "true"
    ```

    <h3 id="manual-step-4">
      Step 4: Create a Kubernetes Secret for the Connect server token
    </h3>

    Create a Kubernetes Secret for your Connect server token. Replace `OP_CONNECT_TOKEN` with the Connect token string or an environment variable that contains the Connect token string.

    ```shell theme={null}
    kubectl create secret generic onepassword-token --from-literal=token="OP_CONNECT_TOKEN"
    ```

    <Tip>
      If you don't already have a Connect server token for the Kubernetes Operator, you can use the following command to create a token and save it as a Kubernetes Secret.

      ```shell theme={null}
      kubectl create secret generic onepassword-token --from-literal=token=$(op connect token create op-k8s-operator --server SERVER --vault VAULT)
      ```

      Make sure to replace `SERVER` with the name (or ID) of the Connect server and `VAULT` with the name (or ID) of the vault.
    </Tip>

    <h3 id="manual-step-5">
      Step 5: Deploy the Kubernetes Operator and Connect server
    </h3>

    Finally, manually deploy the Kubernetes Operator by running `make deploy`.

    <Warning>
      You must clone the [Kubernetes Operator repository <Icon icon="github" />](https://github.com/1Password/onepassword-operator) before you can manually deploy the Kubernetes Operator.
    </Warning>

    1. Clone the [Kubernetes Operator repository <Icon icon="github" />](https://github.com/1Password/onepassword-operator).
    2. Run `make deploy`.

    <Tip>
      Run the following command to check if the CRDs installed correctly:

      ```shell theme={null}
      kubectl get crd onepassworditems.onepassword.com
      ```
    </Tip>
  </Tab>

  <Tab title="Deploy manually with a service account">
    To deploy the Kubernetes Operator with a service account, first [create a service account](/service-accounts/get-started/#create-a-service-account). Then follow these steps:

    ### 1. Create a Kubernetes secret for the service account

    1. Set the `OP_SERVICE_ACCOUNT_TOKEN` environment variable to the service account token you created in step 1. This token will be used by the Operator to access 1Password items.
    2. Create a Kubernetes secret:

    ```shell theme={null}
    kubectl create secret generic onepassword-service-account-token --from-literal=token="$OP_SERVICE_ACCOUNT_TOKEN"
    ```

    ### 2. Deploy the Operator

    To use the Operator with a service account, you need to set the `OP_SERVICE_ACCOUNT_TOKEN` environment variable in the `/config/manager/manager.yaml` file and remove the environment variables `OP_CONNECT_TOKEN` and `OP_CONNECT_HOST`.

    To configure the 1Password Kubernetes Operator, the following environment variables can be set in the Operator YAML file:

    * `OP_SERVICE_ACCOUNT_TOKEN` (required): Specifies a service account token within Kubernetes to access the 1Password items.
    * `WATCH_NAMESPACE`: A comma-separated list of namespaces to watch for changes. The default is `watch all namespaces`.
    * `POLLING_INTERVAL`: The number of seconds the 1Password Kubernetes Operator will wait before checking for updates from 1Password. The default is `600`.
    * `AUTO_RESTART`: If set to true, the Operator will restart any deployment using a secret from 1Password. This can be overwritten by a namespace, deployment, or individual secret. The default is `false`.

    After you've set the environment variables, run the following command to deploy the Operator:

    ```shell theme={null}
    make deploy
    ```

    You can view a sample YAML file [in the onepassword-operator repository on GitHub. <Icon icon="arrow-up-right-from-square" />](https://github.com/1Password/onepassword-operator/blob/main/config/manager/manager.yaml)
  </Tab>
</Tabs>

## Usage examples

Use the following usage examples to help you get started:

* [Create a Kubernetes Secret from a 1Password item](#kubernetes-secret-from-item)
  * [Deploy with a single Kubernetes Secret](#deploy-single)
* [Ignore updates for a Kubernetes Secret](#ignore-updates)
* [Enable automatic redeployment](#enable-auto-redeployment)
  * [Per Kubernetes Operator](#per-kubernetes-operator)
  * [Per namespace](#per-namespace)
  * [Per Kubernetes deployment](#per-kubernetes-deployment)
  * [Per OnePasswordItem](#per-onepassworditem)

<h3 id="kubernetes-secret-from-item">
  Create a Kubernetes Secret from a 1Password item
</h3>

With the Kubernetes Operator deployed, you can create [Kubernetes Secrets <Icon icon="arrow-up-right-from-square" />](https://kubernetes.io/docs/concepts/configuration/secret/) from 1Password items by creating a YAML file and then using `kubectl` to deploy it to your Kubernetes cluster.

The YAML file tells the Kubernetes Operator to create a Kubernetes Secret from a `OnePasswordItem` (a 1Password item) and specifies the item name and the path of the item.

1. Create a YAML file (`1password-item.yaml`) for the 1Password item using the following template. Replace `SECRET_NAME`, `VAULT`, and `ITEM` with the correct values for your 1Password item.

   * Replace `SECRET_NAME` with the name to use to create the Kubernetes Secret.
   * Replace `VAULT` with the name or ID of the vault.
   * Replace `ITEM` with the ID or title of the 1Password item.

   ```yaml 1password-item.yaml theme={null}
   apiVersion: onepassword.com/v1
   kind: OnePasswordItem
   metadata:
     name: SECRET_NAME
   spec:
     itemPath: "vaults/VAULT/items/ITEM"
   ```

2. Use `kubectl` to deploy the `1password-item.yaml` file.

   ```shell theme={null}
   kubectl apply -f 1password-item.yaml
   ```

   ```shell theme={null}
   kubectl get secret 1password-item.yaml
   ```

<Warning>
  If you delete the 1Password item you created, the Kubernetes Operator automatically deletes the corresponding Kubernetes Secret.
</Warning>

<h4 id="deploy-single">
  Deploy with a single Kubernetes Secret
</h4>

You can also create a single Kubernetes Secret for a Kubernetes deployment by adding specific metadata to the deployment specification file and then applying it.

1. Add the following annotations to the deployment specification file:

   ```yaml deployment-specification.yaml theme={null}
   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: deployment-example
     annotations:
       operator.1password.io/item-path: "vaults/VAULT/items/ITEM"
       operator.1password.io/item-name: "SECRET_NAME"
   ```

   Replace `VAULT`, `ITEM`, and `SECRET_NAME`, with the correct values for your 1Password item.

   * Replace `VAULT` with the name or ID of the vault.
   * Replace `ITEM` with the ID or title of the 1Password item.
   * Replace `SECRET_NAME` with the name to use to create the Kubernetes Secret.

2. Apply the YAML file. This creates a Kubernetes Secret named `SECRET_NAME` with the content from the 1Password item specified in the `operator.1password.io/item-path`.

   ```shell theme={null}
   kubectl apply -f deployment-specification.yaml
   ```

<h3 id="ignore-updates">
  Ignore updates for a Kubernetes Secret
</h3>

The Kubernetes Operator automatically keeps Kubernetes Secrets in sync with the corresponding 1Password items.

If a 1Password Item linked to a Kubernetes Secret changes within the `POLLING_INTERVAL`, the associated Kubernetes Secret automatically updates.

You can prevent a specific Kubernetes Secret from updating by adding the annotation `operator.1password.io:ignore-secret` to the item stored in 1Password. While this annotation is in place, the Kubernetes Secret won't update when the associated 1Password item updates.

<h3 id="enable-auto-redeployment">
  Enable automatic redeployment
</h3>

The Kubernetes Operator supports automatic redeployment, which automatically restarts Kubernetes deployments when it detects that a 1Password item linked to a Kubernetes Secret has been updated. When enabled, the Kubernetes Operator restarts Kubernetes deployments that meet the following criteria each time the Connect server polls for updates:

* Its scope is configured to automatically restart.
* It's using a Kubernetes Secret linked to a 1Password item that's been updated.

You can configure automatic redeployment for different scopes:

* [Per Kubernetes Operator](#per-kubernetes-operator)
* [Per namespace](#per-namespace)
* [Per Kubernetes deployment](#per-kubernetes-deployment)
* [Per OnePasswordItem](#per-onepassworditem)

When you configure automatic deployment in a scope (such as per namespace), the configuration applies to all downstream scopes unless you explicitly specify a different configuration for the scope.

#### Per Kubernetes Operator

You can configure automatic redeployment per Kubernetes Operator, which includes all Kubernetes deployments within the namespaces watched by the Kubernetes Operator instance.

The Kubernetes Operator automatic redeployment setting is controlled by the `AUTO_RESTART` environment variable. By default, it's set to `false`. To enable automatic redeployment, set it to `true`.

#### Per namespace

You can configure automatic redeployment per namespace, which includes all Kubernetes deployments within the namespace.

* To turn on automatic redeployment for all Kubernetes deployments within a namespace, set the `operator.1password.io/auto-restart` annotation to `true`.
* To turn off automatic redeployment for all Kubernetes deployments within a namespace, set the `operator.1password.io/auto-restart` annotation to `false`.

Each namespace uses the Kubernetes Operator setting for automatic redeployment if you don't set the `operator.1password.io/auto-restart` annotation value.

The following code block shows an example namespace configuration with automatic redeployment enabled for all Kubernetes deployments within the namespace.

```yaml deployment-specification.yaml highlight={6} theme={null}
apiVersion: v1
kind: Namespace
metadata:
  name: "example-namespace"
  annotations:
    operator.1password.io/auto-restart: "true"
```

#### Per Kubernetes deployment

You can configure automatic redeployment per individual Kubernetes deployment:

* To turn on automatic redeployment for a specific Kubernetes deployment, set the `operator.1password.io/auto-restart` annotation to `true`.
* To turn off automatic redeployment for a specific Kubernetes deployment, set the `operator.1password.io/auto-restart` annotation to `false`.

Each Kubernetes deployment uses the namespace setting for automatic redeployment if you don't set the `operator.1password.io/auto-restart` annotation value.

The following code block shows an example deployment configuration with automatic redeployment enabled.

```yaml deployment-specification.yaml highlight={6} theme={null}
apiVersion: v1
kind: Deployment
metadata:
  name: "example-deployment"
  annotations:
    operator.1password.io/auto-restart: "true"
```

#### Per OnePasswordItem

You can configure automatic redeployment for a specific 1Password item (`OnePasswordItem`) custom resource:

* To turn on automatic redeployment for a specific 1Password item custom resource, set the `operator.1password.io/auto-restart` annotation value to `true`.
* To turn off automatic redeployment for a specific 1Password item custom resource, set the `operator.1password.io/auto-restart` annotation value to `false`.

Each 1Password item (`OnePasswordItem`) uses the Kubernetes deployment setting for automatic redeployment if you don't set the `operator.1password.io/auto-restart` annotation value.

The following code block shows an example of a 1Password item configuration with automatic redeployment enabled.

```yaml deployment-specification.yaml highlight={6} theme={null}
apiVersion: onepassword.com/v1
kind: OnePasswordItem
metadata:
  name: example
  annotations:
    operator.1password.io/auto-restart: "true"
```

## Behavior

The 1Password Kubernetes Connect Operator follows the Kubernetes Operator pattern. It uses Controllers, which provide a reconcile function that synchronizes resources until it reaches the desired cluster state.

Visit the Kubernetes documentation to learn more about the [Operator pattern <Icon icon="arrow-up-right-from-square" />](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/) and [Controllers <Icon icon="arrow-up-right-from-square" />](https://kubernetes.io/docs/concepts/architecture/controller/).

The information in this section documents some of the behavior of the Kubernetes Operator in specific scenarios.

* [Deployment deletion](#deployment-deletion)
* [Fields storing files](#fields-storing-files)
* [Whitespace characters](#whitespace-characters)

### Deployment deletion

Deleting the Deployment you've created deletes the Kubernetes Secret deployment if all the following are true:

1. The deployment has the `operator.1password.io/item-path` and `operator.1password.io/item-name` annotations.
2. No other deployments are using the secret.

### Fields storing files

If a 1Password item field stores a file, the corresponding Kubernetes Secret uses the file's contents as the value. If a single 1Password item has a field storing a file and a field storing another type of data, the Kubernetes Operator prefers the non-file field and ignores the field containing a file.

### Whitespace characters

Titles and field names that include whitespace characters (or any other characters invalid for DNS subdomain names) result in the Kubernetes Operator changing the titles (or fields) in the following manner when creating Kubernetes Secrets:

* Remove invalid characters before the first alphanumeric character.
* Remove invalid characters after the last alphanumeric character.
* Replace whitespace characters between words with a dash (`-`).
* Convert letters to lowercase.

## Configuration

The following section describes the Kubernetes Operator (`1password/onepassword-operator`) container configuration options and their default values. The [example Kubernetes deployment specification file <Icon icon="arrow-up-right-from-square" />](https://kubernetes.io/docs/tasks/inject-data-application/distribute-credentials-secure/#define-container-environment-variables-using-secret-data) shows these configuration values in context.

### Environment variables

| **Environment variable** | **Description**                                                                                                                                                                               | **Required**                                   | **Default value**                                                                                                                                                                                           |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OP_CONNECT_HOST`        | The hostname of the Connect server within Kubernetes.                                                                                                                                         | <span class="badge badge--primary">Yes</span>  | `http://onepassword-connect:8080`                                                                                                                                                                           |
| `WATCH_NAMESPACE`        | A comma-separated list of namespaces to watch for changes. By default, it watches all namespaces.                                                                                             | <span class="badge badge--secondary">No</span> | default (watch all namespaces)                                                                                                                                                                              |
| `POLLING_INTERVAL`       | The number of seconds the Kubernetes Operator should wait before checking for updates from the Connect server.                                                                                | <span class="badge badge--secondary">No</span> | `600`                                                                                                                                                                                                       |
| `MANAGE_CONNECT`         | Whether or not the Kubernetes Operator should deploy with the Connect server in the current namespace with the default configuration.                                                         | <span class="badge badge--secondary">No</span> | `false`                                                                                                                                                                                                     |
| `AUTO_RESTART`           | Whether or not the Kubernetes Operator should redeploy when it detects a secret change from the Connect server.  You can overwrite this value by namespace, deployment, or individual secret. | <span class="badge badge--secondary">No</span> | `false`                                                                                                                                                                                                     |
| `OP_CONNECT_TOKEN`       | A reference to the Kubernetes Secret that contains your Connect server token.                                                                                                                 | <span class="badge badge--primary">Yes</span>  | [secretKeyRef <Icon icon="arrow-up-right-from-square" />](https://kubernetes.io/docs/tasks/inject-data-application/distribute-credentials-secure/#define-container-environment-variables-using-secret-data) |

### Command arguments

| **Argument**      | **Description**                                                                                                          | **Default value** |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------------- |
| `--zap-log-level` | Specify the logging level of detail for the Kubernetes Operator. The available options are `debug`, `info`, and `error`. | `debug`           |