> ## 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 Injector

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 Kubernetes Secrets Injector implements a mutating webhook that allows you to inject 1Password secrets using a [service account](/service-accounts/) or a [Connect server](/connect/) to authenticate to 1Password.

Unlike the 1Password [Kubernetes Operator](/k8s/operator/), the Secrets Injector doesn't create a Kubernetes Secret when assigning secrets to your resource. See [Kubernetes integrations](/k8s/integrations/) to compare the Kubernetes Operator and the Kubernetes Injector.

<Tip>
  Learn how to use the Kubernetes Secrets Injector with a 1Password Service Account.

  <YouTubeVideo src="https://www.youtube.com/embed/WS1CAooBqog" title="Using 1Password Service Accounts with Kubernetes Secrets Injector" />
</Tip>

## Requirements

Before using the Kubernetes Injector, make sure you:

* [Sign up for 1Password](https://1password.com/pricing/password-manager).
* Have a Kubernetes deployment. You can also use [minikube <Icon icon="arrow-up-right-from-square" />](https://minikube.sigs.k8s.io/docs/start/) to test locally.
* Create either a [service account](/service-accounts/get-started/) or a [Connect server](/connect/get-started/#step-1) to authenticate to 1Password.

## Limitations

There are some limitations and nuances to consider about the Kubernetes Injector. For example:

* The Kubernetes Injector requires deployment specifications to use the `command` field.
* Secrets aren't available to all a container's sessions by default.

### The `command` field

The Kubernetes Secrets Injector works by changing the `command` value on initialization. As a result, the pod you want to inject secrets into must have a `command` value defined in its [deployment specification <Icon icon="arrow-up-right-from-square" />](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) file (as shown in the following code block).

See the `command` field in the code block below. In this example, a 1Password Service Account injects secrets into the application run by `npm` `start`.

```yaml deployment-specification.yaml theme={null}
spec:
      containers:
        - name: app-example1
          image: my-image
          ports:
            - containerPort: 5000
          command: ["npm"]
          args: ["start"]
          env:
          - name: OP_SERVICE_ACCOUNT_TOKEN
            valueFrom:
              secretKeyRef:
                name: op-service-account
                key: token
          - name: DB_USERNAME
            value: op://my-vault/my-item/sql/username
          - name: DB_PASSWORD
            value: op://my-vault/my-item/sql/password
```

If the deployments you're using aren't designed to have a command field specified in the deployment, then the 1Password [Kubernetes Operator](/k8s/operator/) might be a better fit for your use case.

### Session availability

Injected secrets are available only in the current pod's session. You can only access the secrets for the command listed in the container specification. To access it in any other session, for example, using `kubectl`, it's necessary to prepend `op run --` to the command.

In the [service account example deployment specification](#usage-examples), the app-example1 container will have injected the `DB_USERNAME` and `DB_PASSWORD` values in the session executed by the command `npm start`.

Another way to have secrets available in all sessions for a container is by using the [Kubernetes Operator](/k8s/operator/).

## Deployment

Use the following instructions to configure and deploy the Kubernetes Injector with your service account or Connect server and Kubernetes deployment.

<p>
  <Accordion title="Notes about strings and variables used in these code examples.">
    Some strings used throughout the code examples on this page are variable and arbitrary. Other strings have specific meanings within the context of 1Password.

    The following strings used in the code examples on this page have very specific and hard-coded meanings within the context of 1Password:

    * `OP_CONNECT_HOST`
    * `OP_CONNECT_TOKEN`
    * `OP_SERVICE_ACCOUNT_TOKEN`

    The following strings used in the code examples on this page have are variables and don't have specific meanings within the context of 1Password:

    * `DB_PASSWORD`
    * `DB_USERNAME`
  </Accordion>
</p>

### Step 1: Enable secrets injection

Use kubectl to enable secrets injection by adding the `secrets-injection=enabled` label to your namespace (`NAMESPACE`)
. The Kubernetes Injector uses the `default` namespace unless you specify a custom namespace.

```shell theme={null}
kubectl label namespace NAMESPACE secrets-injection=enabled
```

### Step 2: Deploy the injector

Use the `kubectl apply` command to the deployment specification files. When you use manual deployment, you must apply each deployment specification file separately.

In the following example, `INJECTOR.yaml` is the name of the Kubernetes Injector deployment specification file and `CONNECT.yaml` is the name of the Connect deployment specification file.

```shell theme={null}
kubectl apply -f INJECTOR.yaml
kubectl apply -f CONNECT.yaml
```

To undeploy, use `kubectl delete`.

```shell theme={null}
kubectl delete -f INJECTOR.yaml
kubectl delete -f CONNECT.yaml
```

The commands in this example only deploy the Kubernetes Injector and Connect. They don't handle additional configuration you might need, like [permissions <Icon icon="arrow-up-right-from-square" />](https://kubernetes.io/docs/tasks/administer-cluster/securing-a-cluster/), [namespaces <Icon icon="arrow-up-right-from-square" />](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/), and [custom resource definitions (CRD) <Icon icon="arrow-up-right-from-square" />](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/).

<Tip>
  You can deploy and configure the Kubernetes Injector in one command if you use the [1Password Secrets Injector Helm chart](/k8s/helm/).
</Tip>

<Note>
  The Kubernetes Injector creates the necessary [TLS certificate <Icon icon="arrow-up-right-from-square" />](https://en.wikipedia.org/wiki/Public_key_certificate) for the webhook when it's deployed ([`deployment.yaml` <Icon icon="github" />](https://github.com/1Password/kubernetes-secrets-injector/blob/main/deploy/deployment.yaml)). If you remove the Kubernetes Injector from the cluster, it automatically deletes the TLS certificate.
</Note>

### Step 3: Annotate your deployment specification

Annotate your [Kubernetes deployment specification <Icon icon="arrow-up-right-from-square" />](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) with `operator.1password.io/inject:` followed by a comma-separated list of the containers you want to mutate and inject secrets into.

1. Edit your deployment specification file and add the following annotation:

   ```yaml deployment-specification.yaml theme={null}
   annotations:
       operator.1password.io/inject: "app-example1, app-example2"
   ```

### Step 4: Configure the resource environment

Add an environment variable to your pod or [Kubernetes deployment specification <Icon icon="arrow-up-right-from-square" />](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) with a value referencing your 1Password item using a [secret reference](/cli/secret-reference-syntax/).

1. Edit your deployment specification file and add an environment variable containing the path to the 1Password item. Make sure to replace `VAULT`
   , `ITEM`, `SECTION`, and `FIELD` with the correct values.

   ```yaml deployment-specification.yaml theme={null}
   env:
     - name: DB_USERNAME
       value: op://VAULT/ITEM[/SECTION]/FIELD
   ```

   The value should look something like the text in the following code block:

   ```yaml deployment-specification.yaml theme={null}
   env:
     - name: DB_USERNAME
       value: op://my-vault/sql/username
   ```

### Step 5: Add your 1Password credentials to your deployment

#### Step 5.1: Create a Kubernetes Secret with your authentication token

To authenticate to 1Password, you'll need to create a [Kubernetes Secret <Icon icon="arrow-up-right-from-square" />](https://kubernetes.io/docs/concepts/configuration/secret/) that contains your service account or Connect server token.

<Tabs queryString="workflow-type" groupId="step-1">
  <Tab title="Service account">
    You can pass your service account token to Kubernetes using the `kubectl create secret` command:

    <Note>
      Your service account token is generated automatically during the service account creation process. If you lose the token, you must [create a new service account](/service-accounts/get-started/).
    </Note>

    ```shell theme={null}
    kubectl create secret generic op-service-account --from-literal=token=YOUR_SERVICE_ACCOUNT_TOKEN
    ```

    This creates a generic Secret named `op-service-account` with a key named `token` that contains your service account token.
  </Tab>

  <Tab title="Connect">
    You can pass your Connect server access token token to Kubernetes using the `kubectl create secret` command:

    ```shell theme={null}
    kubectl create secret generic connect-token --from-literal=token=YOUR_CONNECT_TOKEN
    ```

    This creates a generic Secret named `connect-token` with a key named `token` that contains your Connect server access token.
  </Tab>
</Tabs>

#### Step 5.2: Add the Secret to your Kubernetes deployment specification file

You can reference the Secret you created for your service account or Connect server token in your [Kubernetes deployment specification file <Icon icon="arrow-up-right-from-square" />](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) using an environment variable. Kubernetes will automatically inject the authentication token into your pod or deployment when it starts.

<Tabs groupId="step-6" queryString="workflow-type">
  <Tab title="Service account">
    Add an environment variable named `OP_SERVICE_ACCOUNT_TOKEN` to your deployment specification file, and set the `valueFrom` to reference the Kubernetes Secret you created in the previous step.

    If you used a custom Secret or key name, make sure to update the example to use the appropriate name and key.

    ```yaml deployment-specification.yaml theme={null}
        spec:
          containers:
            - name: app-example1
              image: my-image
              ports:
                - containerPort: 5000
              command: ["npm"]
              args: ["start"]
              env:
              - name: OP_SERVICE_ACCOUNT_TOKEN
                valueFrom:
                  secretKeyRef:
                    name: op-service-account
                    key: token
    ```
  </Tab>

  <Tab title="Connect">
    1. Add an environment variable named `OP_CONNECT_HOST` to your deployment specification file for your Connect server host. Set the `value` to the URL where your Connect server is deployed.
    2. Add an environment variable named `OP_CONNECT_TOKEN`, and set the `valueFrom` to reference the Kubernetes Secret you created in the previous step. If you used a custom Secret or key name, make sure to update the example to use the appropriate name and key.

    ```yaml deployment-specification.yaml theme={null}
        spec:
          containers:
            - name: app-example1
              image: my-image
              ports:
                - containerPort: 5000
              command: ["npm"]
              args: ["start"]
              env:
              - name: OP_CONNECT_HOST
                value: http://onepassword-connect:8080
              - name: OP_CONNECT_TOKEN
                valueFrom:
                  secretKeyRef:
                    name: connect-token
                    key: token
    ```
  </Tab>
</Tabs>

<Warning>
  If you configure the Kubernetes Injector to authenticate with both a service account and a Connect server, the Connect server will take precedence.
</Warning>

## Usage examples

The following Kubernetes deployment specification files show what your deployment file should look like.

<Tabs groupId="examples" queryString="workflow-type">
  <Tab title="Service account">
    The following code block contains an example of a Kubernetes deployment specification YAML file setup to inject secrets using a 1Password Service Account. In this example, the Kubernetes Injector injects secrets into `APP_1`, but not `APP_2`.

    ```yaml deployment-specification.yaml theme={null}
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: app-example
    spec:
      selector:
        matchLabels:
          app: app-example
      template:
        metadata:
          annotations:
            operator.1password.io/inject: APP_1
          labels:
            app: app-example
        spec:
          containers:
            - name: APP_1
              image: my-image
              ports:
                - containerPort: 5000
              command: ["npm"]
              args: ["start"]
              env:
              - name: OP_SERVICE_ACCOUNT_TOKEN
                valueFrom:
                  secretKeyRef:
                    name: op-service-account
                    key: token
              - name: DB_USERNAME
                value: op://my-vault/my-item/sql/username
              - name: DB_PASSWORD
                value: op://my-vault/my-item/sql/password
            - name: APP_2
              image: my-image
              ports:
                - containerPort: 5000
              command: ["npm"]
              args: ["start"]
              env:
              - name: DB_USERNAME
                value: op://my-vault/my-item/sql/username
              - name: DB_PASSWORD
                value: op://my-vault/my-item/sql/password
    ```
  </Tab>

  <Tab title="Connect">
    The following code block contains an example of a Kubernetes deployment specification YAML file setup to inject secrets using a 1Password Connect Server. In this example, the Kubernetes Injector injects secrets into `APP_1`, but not `APP_2`.

    ```yaml deployment-specification.yaml theme={null}
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: app-example
    spec:
      selector:
        matchLabels:
          app: app-example
      template:
        metadata:
          annotations:
            operator.1password.io/inject: APP_1
          labels:
            app: app-example
        spec:
          containers:
            - name: APP_1
              image: my-image
              ports:
                - containerPort: 5000
              command: ["npm"]
              args: ["start"]
              env:
              - name: OP_CONNECT_HOST
                value: http://onepassword-connect:8080
              - name: OP_CONNECT_TOKEN
                valueFrom:
                  secretKeyRef:
                    name: connect-token
                    key: token-value
              - name: DB_USERNAME
                value: op://my-vault/my-item/sql/username
              - name: DB_PASSWORD
                value: op://my-vault/my-item/sql/password
            - name: APP_2
              image: my-image
              ports:
                - containerPort: 5000
              command: ["npm"]
              args: ["start"]
              env:
              - name: DB_USERNAME
                value: op://my-vault/my-item/sql/username
              - name: DB_PASSWORD
                value: op://my-vault/my-item/sql/password
    ```
  </Tab>
</Tabs>