Kubernetes Operator - 1Password Developer Docs

The 1Password Connect Kubernetes Operator integrates Kubernetes Secrets 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.

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.

Deploy with Helm
Deploy manually with Connect
Deploy manually with a service account

Before you can deploy the Kubernetes Operator with the 1Password Connect and Operator Helm chart, you must:

Sign up for 1Password.
Install 1Password CLI.
Have a Kubernetes deployment. You can also use minikube to test locally.
Install Helm .
Create a Secrets Automation workflow as a Connect server. You need the Connect server’s 1password-credentials.json file.

Before you can deploy the Kubernetes Operator with a Kubernetes deployment specification file, you must:

Sign up for 1Password.
Install 1Password CLI.
Have a Kubernetes deployment. You can also use minikube to test locally.
Create a Secrets Automation workflow as a Connect server. You need the Connect server’s 1password-credentials.json file.

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.

Deployment

There are two ways to deploy the Kubernetes Operator:

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

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

Deploy with Helm
Deploy manually with Connect
Deploy manually with a service account

The following instructions cover deploying the Kubernetes Operator using the 1Password Connect and Operator Helm chart.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 to your local instance of Helm. This allows you to download and install all charts from 1Password’s GitHub repository.

helm repo add 1password https://1password.github.io/connect-helm-charts/

Step 2. Install the Kubernetes Operator using Helm

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.

With Connect
Without Connect
With a service account

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.

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.

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)

To install the Kubernetes Operator without Connect, set operator.create to true and connect.create to false.

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.

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

To install the Kubernetes Operator with a service account, set operator.create to true, connect.create to false, and operator.authMethod to service-account.

helm install connect 1password/connect --set operator.create=true --set connect.create=false --set operator.authMethod=service-account --set operator.serviceAccountToken.value=<token>

The following instructions cover deploying the Kubernetes Operator manually, using a Kubernetes deployment specification .

Create a deployment specification.
Create a Kubernetes Secret from the Connect server credentials.
Add the MANAGE_CONNECT environment variable.
Create a Kubernetes Secret for the Connect server token.
Deploy the Kubernetes Operator.

Step 1: Create a deployment specification

Create a Kubernetes deployment specification YAML file. You can use the example 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.

Step 2: Create a Kubernetes Secret from the Connect server credentials

Encode the 1password-credentials.json file you generated when you created your Connect server and name it FILE_NAME.
```
cat 1password-credentials.json | base64 | \  tr '/+' '_-' | tr -d '=' | tr -d '\n' > FILE_NAME
```
Use kubectl to create a Kubernetes Secret from the encoded FILE_NAME file.
```
kubectl create secret generic op-credentials --from-file=FILE_NAME
```

Step 3: Add the `MANAGE_CONNECT` environment variable

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.

deployment-specification.yaml

- name: MANAGE_CONNECT
  value: "true"

Step 4: Create a Kubernetes Secret for the Connect server token

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.

kubectl create secret generic onepassword-token --from-literal=token="OP_CONNECT_TOKEN"

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.

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.

Step 5: Deploy the Kubernetes Operator and Connect server

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

You must clone the Kubernetes Operator repository before you can manually deploy the Kubernetes Operator.

Clone the Kubernetes Operator repository .
Run make deploy.

Run the following command to check if the CRDs installed correctly:

kubectl get crd onepassworditems.onepassword.com

To deploy the Kubernetes Operator with a service account, first create a service account. Then follow these steps:

1. Create a Kubernetes secret for the service account

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.
Create a Kubernetes secret:

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:

make deploy

You can view a sample YAML file in the onepassword-operator repository on GitHub.

Usage examples

Use the following usage examples to help you get started:

Create a Kubernetes Secret from a 1Password item
- Deploy with a single Kubernetes Secret
Ignore updates for a Kubernetes Secret
Enable automatic redeployment

Create a Kubernetes Secret from a 1Password item

With the Kubernetes Operator deployed, you can create Kubernetes Secrets 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.

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.
1password-item.yaml
```
apiVersion: onepassword.com/v1
kind: OnePasswordItem
metadata:
  name: SECRET_NAME
spec:
  itemPath: "vaults/VAULT/items/ITEM"
```
Use kubectl to deploy the 1password-item.yaml file.
```
kubectl apply -f 1password-item.yaml
```
```
kubectl get secret 1password-item.yaml
```

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

Deploy with a single Kubernetes Secret

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.

Add the following annotations to the deployment specification file:
deployment-specification.yaml
```
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.
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.
```
kubectl apply -f deployment-specification.yaml
```

Ignore updates for a Kubernetes Secret

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.

Enable automatic redeployment

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 namespace
Per Kubernetes deployment
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.

deployment-specification.yaml

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.

deployment-specification.yaml

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.

deployment-specification.yaml

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 and Controllers . The information in this section documents some of the behavior of the Kubernetes Operator in specific scenarios.

Deployment deletion
Fields storing files
Whitespace characters

Deployment deletion

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

The deployment has the operator.1password.io/item-path and operator.1password.io/item-name annotations.
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 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.	Yes	`http://onepassword-connect:8080`
`WATCH_NAMESPACE`	A comma-separated list of namespaces to watch for changes. By default, it watches all namespaces.	No	default (watch all namespaces)
`POLLING_INTERVAL`	The number of seconds the Kubernetes Operator should wait before checking for updates from the Connect server.	No	`600`
`MANAGE_CONNECT`	Whether or not the Kubernetes Operator should deploy with the Connect server in the current namespace with the default configuration.	No	`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.	No	`false`
`OP_CONNECT_TOKEN`	A reference to the Kubernetes Secret that contains your Connect server token.	Yes	secretKeyRef

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`

Integrations

​Requirements

​Limitations

​Deployment

​Step 1. Add the 1Password Helm chart repository

​Step 2. Install the Kubernetes Operator using Helm

​Step 1: Create a deployment specification

​Step 2: Create a Kubernetes Secret from the Connect server credentials

​Step 3: Add the MANAGE_CONNECT environment variable

​Step 4: Create a Kubernetes Secret for the Connect server token

​Step 5: Deploy the Kubernetes Operator and Connect server

​1. Create a Kubernetes secret for the service account

​2. Deploy the Operator

​Usage examples

​Create a Kubernetes Secret from a 1Password item

​Deploy with a single Kubernetes Secret

​Ignore updates for a Kubernetes Secret

​Enable automatic redeployment

​Per Kubernetes Operator

​Per namespace

​Per Kubernetes deployment

​Per OnePasswordItem

​Behavior

​Deployment deletion

​Fields storing files

​Whitespace characters

​Configuration

​Environment variables

​Command arguments

Requirements

Limitations

Deployment

Step 1. Add the 1Password Helm chart repository

Step 2. Install the Kubernetes Operator using Helm

Step 1: Create a deployment specification

Step 2: Create a Kubernetes Secret from the Connect server credentials

Step 3: Add the `MANAGE_CONNECT` environment variable

Step 4: Create a Kubernetes Secret for the Connect server token

Step 5: Deploy the Kubernetes Operator and Connect server

1. Create a Kubernetes secret for the service account

2. Deploy the Operator

Usage examples

Create a Kubernetes Secret from a 1Password item

Deploy with a single Kubernetes Secret

Ignore updates for a Kubernetes Secret

Enable automatic redeployment

Per Kubernetes Operator

Per namespace

Per Kubernetes deployment

Per OnePasswordItem

Behavior

Deployment deletion

Fields storing files

Whitespace characters

Configuration

Environment variables

Command arguments