1Password/onepassword-operator
1
0
Fork 0
mirror of https://github.com/1Password/onepassword-operator.git synced 2025-10-22 07:28:06 +00:00
Code Issues Packages Projects Releases Wiki Activity

update README.md

Browse Source
This commit is contained in:
volodymyrZotov
2022-10-19 17:44:22 +03:00
parent 916015cd75
commit c4fdcc6f5f
1 changed files with 43 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

48
README.md
View File

@@ -6,6 +6,14 @@ The 1Password Connect Kubernetes Operator also allows for Kubernetes Secrets to
The 1Password Connect Kubernetes Operator will continually check for updates from 1Password for any Kubernetes Secret that it has generated. If a Kubernetes Secret is updated, any Deployment using that secret can be automatically restarted. The 1Password Connect Kubernetes Operator will continually check for updates from 1Password for any Kubernetes Secret that it has generated. If a Kubernetes Secret is updated, any Deployment using that secret can be automatically restarted.
- [Setup](#setup)
- [Quickstart for Deploying 1Password Connect to Kubernetes](#quickstart-for-deploying-1password-connect-to-kubernetes)
- [Kubernetes Operator Deployment](#kubernetes-operator-deployment)
- [Usage](#usage)
- [Configuring Automatic Rolling Restarts of Deployments](#configuring-automatic-rolling-restarts-of-deployments)
- [Development](#development)
- [Security](#security)
## Setup ## Setup
Prerequisites: Prerequisites:
@@ -13,10 +21,13 @@ Prerequisites:
- [1Password Command Line Tool Installed](https://1password.com/downloads/command-line/) - [1Password Command Line Tool Installed](https://1password.com/downloads/command-line/)
- [kubectl installed](https://kubernetes.io/docs/tasks/tools/install-kubectl/) - [kubectl installed](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
- [docker installed](https://docs.docker.com/get-docker/) - [docker installed](https://docs.docker.com/get-docker/)
- [Generated a 1password-credentials.json file and issued a 1Password Connect API Token for the K8s Operator integration](https://support.1password.com/secrets-automation/) - [Generated a 1password-credentials.json file and issued a 1Password Connect API Token for the K8s Operator integration](https://developer.1password.com/docs/connect/get-started/#step-1-set-up-a-secrets-automation-workflow)
- [1Password Connect deployed to Kubernetes](https://support.1password.com/connect-deploy-kubernetes/#step-2-deploy-a-1password-connect-server). **NOTE**: If customization of the 1Password Connect deployment is not required you can skip this prerequisite. - [1Password Connect deployed to Kubernetes](#quickstart-for-deploying-1password-connect-to-kubernetes). **NOTE**: If customization of the 1Password Connect deployment is not required you can skip this prerequisite.
### Quickstart for Deploying 1Password Connect to Kubernetes ## Quickstart for Deploying 1Password Connect to Kubernetes
There are options to deploy 1Password Connect:
- [Deploy with Helm](#deploy-with-helm)
- [Deploy along with Operator](#deploy-along-with-operator)
#### Deploy with Helm #### Deploy with Helm
The 1Password Connect Helm Chart helps to simplify the deployment of 1Password Connect and the 1Password Connect Kubernetes Operator to Kubernetes. The 1Password Connect Helm Chart helps to simplify the deployment of 1Password Connect and the 1Password Connect Kubernetes Operator to Kubernetes.
@@ -38,12 +49,12 @@ Create a Kubernetes secret from the op-session file:
kubectl create secret generic op-credentials --from-file=op-session kubectl create secret generic op-credentials --from-file=op-session
``` ```
Add the following environment variable to the onepassword-connect-operator container in `deploy/operator.yaml`: Add the following environment variable to the onepassword-connect-operator container in `/config/manager/manager.yaml`:
```yaml ```yaml
- name: MANAGE_CONNECT - name: MANAGE_CONNECT
value: "true" value: "true"
``` ```
Adding this environment variable will have the operator automatically deploy a default configuration of 1Password Connect to the `default` namespace. Adding this environment variable will have the operator automatically deploy a default configuration of 1Password Connect to the current namespace.
### Kubernetes Operator Deployment ### Kubernetes Operator Deployment
@@ -60,6 +71,11 @@ If you do not have a token for the operator, you can generate a token and save i
kubectl create secret generic onepassword-token --from-literal=token=$(op create connect token <server> op-k8s-operator --vault <vault>) kubectl create secret generic onepassword-token --from-literal=token=$(op create connect token <server> op-k8s-operator --vault <vault>)
``` ```
**Build Operator docker image**
```
make docker-build
```
**Deploying the Operator** **Deploying the Operator**
An sample Deployment yaml can be found at `/config/manager/manager.yaml`. An sample Deployment yaml can be found at `/config/manager/manager.yaml`.
@@ -69,7 +85,7 @@ To further configure the 1Password Kubernetes Operator the Following Environment
- **OP_CONNECT_HOST** (required): Specifies the host name within Kubernetes in which to access the 1Password Connect. - **OP_CONNECT_HOST** (required): Specifies the host name within Kubernetes in which to access the 1Password Connect.
- **WATCH_NAMESPACE:** (default: watch all namespaces): Comma separated list of what Namespaces to watch for changes. - **WATCH_NAMESPACE:** (default: watch all namespaces): Comma separated list of what Namespaces to watch for changes.
- **POLLING_INTERVAL** (default: 600): The number of seconds the 1Password Kubernetes Operator will wait before checking for updates from 1Password Connect. - **POLLING_INTERVAL** (default: 600): The number of seconds the 1Password Kubernetes Operator will wait before checking for updates from 1Password Connect.
- **MANAGE_CONNECT** (default: false): If set to true, on deployment of the operator, a default configuration of the OnePassword Connect Service will be deployed to the `default` namespace. - **MANAGE_CONNECT** (default: false): If set to true, on deployment of the operator, a default configuration of the OnePassword Connect Service will be deployed to the current namespace.
- **AUTO_RESTART** (default: false): If set to true, the operator will restart any deployment using a secret from 1Password Connect. This can be overwritten by namespace, deployment, or individual secret. More details on AUTO_RESTART can be found in the ["Configuring Automatic Rolling Restarts of Deployments"](#configuring-automatic-rolling-restarts-of-deployments) section. - **AUTO_RESTART** (default: false): If set to true, the operator will restart any deployment using a secret from 1Password Connect. This can be overwritten by namespace, deployment, or individual secret. More details on AUTO_RESTART can be found in the ["Configuring Automatic Rolling Restarts of Deployments"](#configuring-automatic-rolling-restarts-of-deployments) section.
To deploy the operator, simply run the following command: To deploy the operator, simply run the following command:
@@ -78,6 +94,11 @@ To deploy the operator, simply run the following command:
make deploy make deploy
``` ```
**Undeploy Operator**
```
make undeploy
```
## Usage ## Usage
To create a Kubernetes Secret from a 1Password item, create a yaml file with the following To create a Kubernetes Secret from a 1Password item, create a yaml file with the following
@@ -129,26 +150,29 @@ Note: Deleting the Deployment that you've created will automatically delete the
If a 1Password Item that is linked to a Kubernetes Secret is updated within the POLLING_INTERVAL the associated Kubernetes Secret will be updated. However, if you do not want a specific secret to be updated you can add the tag `operator.1password.io:ignore-secret` to the item stored in 1Password. While this tag is in place, any updates made to an item will not trigger an update to the associated secret in Kubernetes. If a 1Password Item that is linked to a Kubernetes Secret is updated within the POLLING_INTERVAL the associated Kubernetes Secret will be updated. However, if you do not want a specific secret to be updated you can add the tag `operator.1password.io:ignore-secret` to the item stored in 1Password. While this tag is in place, any updates made to an item will not trigger an update to the associated secret in Kubernetes.
--- ---
**NOTE** **NOTE**
If multiple 1Password vaults/items have the same `title` when using a title in the access path, the desired action will be performed on the oldest vault/item. If multiple 1Password vaults/items have the same `title` when using a title in the access path, the desired action will be performed on the oldest vault/item.
Titles and field names that include white space and other characters that are not a valid [DNS subdomain name](https://kubernetes.io/docs/concepts/configuration/secret/) will create Kubernetes secrets that have titles and fields in the following format: Titles and field names that include white space and other characters that are not a valid [DNS subdomain name](https://kubernetes.io/docs/concepts/configuration/secret/) will create Kubernetes secrets that have titles and fields in the following format:
- Invalid characters before the first alphanumeric character and after the last alphanumeric character will be removed - Invalid characters before the first alphanumeric character and after the last alphanumeric character will be removed
- All whitespaces between words will be replaced by `-` - All whitespaces between words will be replaced by `-`
- All the letters will be lower-cased. - All the letters will be lower-cased.
--- ---
### Configuring Automatic Rolling Restarts of Deployments ## Configuring Automatic Rolling Restarts of Deployments
If a 1Password Item that is linked to a Kubernetes Secret is updated, any deployments configured to `auto-restart` AND are using that secret will be given a rolling restart the next time 1Password Connect is polled for updates. If a 1Password Item that is linked to a Kubernetes Secret is updated, any deployments configured to `auto-restart` AND are using that secret will be given a rolling restart the next time 1Password Connect is polled for updates.
There are many levels of granularity on which to configure auto restarts on deployments: at the operator level, per-namespace, or per-deployment. There are many levels of granularity on which to configure auto restarts on deployments: at the operator level, per-namespace, or per-deployment.
**On the operator**: This method allows for managing auto restarts on all deployments within the namespaces watched by operator. Auto restarts can be enabled by setting the environemnt variable `AUTO_RESTART` to true. If the value is not set, the operator will default this value to false. **On the operator**: This method allows for managing auto restarts on all deployments within the namespaces watched by operator. Auto restarts can be enabled by setting the environemnt variable `AUTO_RESTART` to true. If the value is not set, the operator will default this value to false.
**Per Namespace**: This method allows for managing auto restarts on all deployments within a namespace. Auto restarts can by managed by setting the annotation `operator.1password.io/auto-restart` to either `true` or `false` on the desired namespace. An example of this is shown below: **Per Namespace**: This method allows for managing auto restarts on all deployments within a namespace. Auto restarts can by managed by setting the annotation `operator.1password.io/auto-restart` to either `true` or `false` on the desired namespace. An example of this is shown below:
```yaml ```yaml
# enabled auto restarts for all deployments within a namespace unless overwritten within a deployment # enabled auto restarts for all deployments within a namespace unless overwritten within a deployment
apiVersion: v1 apiVersion: v1
@@ -158,10 +182,12 @@ metadata:
annotations: annotations:
operator.1password.io/auto-restart: "true" operator.1password.io/auto-restart: "true"
``` ```
If the value is not set, the auto restart settings on the operator will be used. This value can be overwritten by deployment. If the value is not set, the auto restart settings on the operator will be used. This value can be overwritten by deployment.
**Per Deployment** **Per Deployment**
This method allows for managing auto restarts on a given deployment. Auto restarts can by managed by setting the annotation `operator.1password.io/auto-restart` to either `true` or `false` on the desired deployment. An example of this is shown below: This method allows for managing auto restarts on a given deployment. Auto restarts can by managed by setting the annotation `operator.1password.io/auto-restart` to either `true` or `false` on the desired deployment. An example of this is shown below:
```yaml ```yaml
# enabled auto restarts for the deployment # enabled auto restarts for the deployment
apiVersion: v1 apiVersion: v1
@@ -171,10 +197,12 @@ metadata:
annotations: annotations:
operator.1password.io/auto-restart: "true" operator.1password.io/auto-restart: "true"
``` ```
If the value is not set, the auto restart settings on the namespace will be used. If the value is not set, the auto restart settings on the namespace will be used.
**Per OnePasswordItem Custom Resource** **Per OnePasswordItem Custom Resource**
This method allows for managing auto restarts on a given OnePasswordItem custom resource. Auto restarts can by managed by setting the annotation `operator.1password.io/auto_restart` to either `true` or `false` on the desired OnePasswordItem. An example of this is shown below: This method allows for managing auto restarts on a given OnePasswordItem custom resource. Auto restarts can by managed by setting the annotation `operator.1password.io/auto_restart` to either `true` or `false` on the desired OnePasswordItem. An example of this is shown below:
```yaml ```yaml
# enabled auto restarts for the OnePasswordItem # enabled auto restarts for the OnePasswordItem
apiVersion: onepassword.com/v1 apiVersion: onepassword.com/v1
@@ -184,6 +212,7 @@ metadata:
annotations: annotations:
operator.1password.io/auto-restart: "true" operator.1password.io/auto-restart: "true"
``` ```
If the value is not set, the auto restart settings on the deployment will be used. If the value is not set, the auto restart settings on the deployment will be used.
<!-- <!--
@@ -228,12 +257,14 @@ make undeploy
## Development ## Development
### How it works ### How it works
This project aims to follow the Kubernetes [Operator pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/) This project aims to follow the Kubernetes [Operator pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/)
It uses [Controllers](https://kubernetes.io/docs/concepts/architecture/controller/) It uses [Controllers](https://kubernetes.io/docs/concepts/architecture/controller/)
which provides a reconcile function responsible for synchronizing resources untile the desired state is reached on the cluster which provides a reconcile function responsible for synchronizing resources untile the desired state is reached on the cluster
### Test It Out ### Test It Out
1. Install the CRDs into the cluster: 1. Install the CRDs into the cluster:
```sh ```sh
@@ -249,6 +280,7 @@ make run
**NOTE:** You can also run this in one step by running: `make install run` **NOTE:** You can also run this in one step by running: `make install run`
### Modifying the API definitions ### Modifying the API definitions
If you are editing the API definitions, generate the manifests such as CRs or CRDs using: If you are editing the API definitions, generate the manifests such as CRs or CRDs using:
```sh ```sh