DOCSEARCHbyAlgolia
Submit Docs

1Password Connect Kubernetes Operator

repository·main·Indexed 20 days ago

https://github.com/1password/onepassword-operator

The 1Password Connect Kubernetes Operator integrates 1Password with Kubernetes by synchronizing 1Password items into Kubernetes Secrets and automating the restarting of deployments when items are updated. It supports authentication via 1Password Connect or Service Account tokens and provides Custom Resources like OnePasswordItem and OnePasswordItemList for secret management.

Tokens
5.8K
Snippets
21
Records
26
Agent score
70%

What's inside onepassword-operator

  1. How E2E testing works for external pull requests

    main

    The 1Password Operator uses two distinct workflows for testing pull requests (PRs) to ensure security and prevent unauthorized resource consumption from external forks:

    1. Internal PRs (Maintainer-created): The E2E Tests (test-e2e.yml) workflow starts automatically upon PR creation. The PR check status reflects the job's progress.
    2. External PRs (Contributor-created): The E2E Tests workflow does not start automatically. To run these tests, a maintainer must manually trigger them using the ok-to-test command.

    Running E2E tests on external PRs is optional; maintainers may choose to merge a PR without running the tests if they deem it unnecessary.

  2. How 1Password Items map to Kubernetes Secrets

    main

    The 1Password Operator synchronizes 1Password items into Kubernetes Secrets.

    Mapping Logic

    • Fields to Keys: Kubernetes secret contents are key-value pairs. Keys are the field names from the 1Password item, and values are the field values.
    • Files: If a field stores a file, the file's contents are used as the value.
    • Conflict Resolution: If a field stores a file and another field of a different type shares the same name, the file field is ignored.
    • Naming Sanitization: Titles and field names containing characters invalid for a DNS subdomain are sanitized:
      • Invalid characters before the first alphanumeric or after the last alphanumeric are removed.
      • Whitespaces are replaced with -.
      • All letters are converted to lowercase.

    Synchronization and Deletion

    • Updates: Secrets are updated within the POLLING_INTERVAL if the 1Password item changes.
    • Ignoring Updates: To prevent a specific secret from being updated, add the tag operator.1password.io:ignore-secret to the item in 1Password.
    • Deletion: Deleting the Deployment will automatically delete the associated Kubernetes Secret only if the deployment is still annotated with operator.1password.io/item-path and operator.1password.io/item-name and no other deployment is using that secret.

  3. Configure automatic rolling restarts of deployments

    main

    When a 1Password Item is updated, you can configure the operator to trigger a rolling restart of any deployment using that secret. This can be configured at four levels of granularity. The most specific setting wins.

    1. Operator Level: Set AUTO_RESTART=true in the operator's environment variables to enable restarts for all watched namespaces.
    2. Namespace Level: Add the annotation operator.1password.io/auto-restart: "true" (or "false") to the Namespace.
    3. Deployment Level: Add the annotation operator.1password.io/auto-restart: "true" (or "false") to the Deployment.
    4. OnePasswordItem Level: Add the annotation operator.1password.io/auto-restart: "true" (or "false") to the OnePasswordItem custom resource.

    Hierarchy of precedence:

    OnePasswordItem > Deployment > Namespace > Operator

    # Namespace level example
apiVersion: v1
kind: Namespace
metadata:
  name: "example-namespace"
  annotations:
    operator.1password.io/auto-restart: "true"

  4. Quickstart: Install 1Password Connect and the Kubernetes Operator

    main

    To integrate 1Password with your Kubernetes infrastructure, you must first add the 1Password Helm Chart to your repository and then install both Connect and the Operator using Helm. This process requires a 1Password Connect credentials file and a Connect token.

    Follow these steps:

    1. Add the 1Password Helm Chart to your repository.
    2. Run the helm install command provided below.
    3. Deploy your OnePasswordItem or OnePasswordItemList resources using kubectl.
    helm install connect 1password/connect \
  --set-file connect.credentials=1password-credentials-demo.json \
  --set operator.create=true \
  --set operator.token.value=<your_connect_token>

  5. Deploy and verify OnePassword resources

    main

    After defining your OnePasswordItem or OnePasswordItemList in a YAML file, deploy it to your cluster and verify the generated secret.

    1. Apply the manifest:
    kubectl apply -f <your_item>.yaml
    1. Verify the secret exists:
    kubectl get secret <secret_name>

  7. Deploy the 1Password Operator using 1Password Connect

    main

    To use the 1Password Operator with 1Password Connect, you can deploy via Helm or manually.

    Configuration Requirements:

    • You must set the OP_CONNECT_HOST environment variable in the operator deployment YAML to specify the hostname within Kubernetes used to access 1Password Connect.

  8. Run End-to-End (E2E) tests with kind

    main

    E2E tests validate full cluster behavior, including CRDs, the operator image, and Connect/Service Account flows. These tests are located in test/e2e/ and use the Ginkgo framework along with the pkg/testhelper package.

    Prerequisites

    1. Install kind to manage local Kubernetes clusters.
    2. Ensure 1password-credentials.json is placed in the project root.

    Setup and Execution

    Set the required environment variables for Connect and Service Account tokens, then run the E2E test command:

    export OP_CONNECT_TOKEN=<token>
export OP_SERVICE_ACCOUNT_TOKEN=<token>
make test-e2e

  10. Trigger E2E tests on an external PR

    main

    To run the E2E Test workflow on a pull request from an external contributor, a maintainer with write permissions must post a specific comment in the PR thread. This dispatches a repository_dispatch event via the ok-to-test.yml workflow.

    Steps to trigger:

    1. Identify the latest commit hash of the PR.
    2. Post a comment in the PR thread using the following format: /ok-to-test sha=<latest commit hash>
    3. The E2E Test workflow will start.
    4. Once finished, a comment containing the workflow status and a link to the run will be automatically posted to the PR.
    /ok-to-test sha=<latest commit hash>

  11. Deploy the 1Password Operator using a Service Account

    main

    To use the 1Password Operator with a Service Account, follow these steps:

    1. Create a Service Account: Follow the 1Password Service Account guide to generate a token.
    2. Create a Kubernetes Secret: Store the token in a secret so the operator can access it.
      kubectl create secret generic onepassword-service-account-token --from-literal=token="$OP_SERVICE_ACCOUNT_TOKEN"
    3. Deploy the Operator: Use make deploy to install the operator.

    Configuration Requirements:

    • In your operator deployment YAML (e.g., /config/manager/manager.yaml), set the OP_SERVICE_ACCOUNT_TOKEN environment variable.
    • Important: You must remove OP_CONNECT_TOKEN and OP_CONNECT_HOST if you are using the Service Account method.
    kubectl create secret generic onepassword-service-account-token --from-literal=token="$OP_SERVICE_ACCOUNT_TOKEN"

  12. Develop the 1Password Operator

    main

    The project follows the Kubernetes Operator pattern using Controllers and a reconcile function.

    Local Development Workflow

    1. Install CRDs: make install installs the Custom Resource Definitions into your cluster.
    2. Run Controller: make run (or make install run) runs the controller in the foreground.
    3. Update API Definitions: If you modify API definitions, run make manifests to generate the necessary manifests (CRs or CRDs).

    Use make --help to see all available targets.

    # Install CRDs and run the controller in one step
make install run