Kubernetes Operator

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

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.

Deploy manually

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 only supports Connect servers. If you're using service accounts, consider using the Kubernetes Injector instead.

Additionally, the Kubernetes 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:

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

caution

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

Deploy with Helm

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.

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

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.

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.

Without Connect

To install the Kubernetes Operator without Connect, set operator.create to true and connect.create to 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.

Deploy manually

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

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

Step 1: Create a deployment specification

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

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

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

Step 3: Add the MANAGE_CONNECT environment variable

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.

deployment-specification.yaml

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.

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.

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.

caution

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

1. Clone the Kubernetes Operator repository .
2. Run make deploy.

tip

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

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
  • Per Kubernetes Operator
  • Per namespace
  • Per Kubernetes deployment
  • Per OnePasswordItem

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.

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.

   1password-item.yaml

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

caution

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.

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

   deployment-specification.yaml

   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.

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

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

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

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:

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