externalsecret-operator

README

External Secret Operator

This operator reads information from a third party service like AWS Secrets Manager or AWS SSM and automatically injects the values as Kubernetes Secrets.

Table of Contents

• Quick start
• Kustomize
• What does it do?
• Architecture
• Spec
• Supported Backends
  • 1-Password
    • Prerequisites
    • Deployment
  • GCP Secret Manager
    • Prerequisites
    • Deployment
• Contributing

Quick start

Using Kustomize

Install the operator CRDs

• Install CRDs

make install

What does it do?

Given a secret defined in AWS Secrets Manager:

% aws secretsmanager create-secret \
  --name=example-externalsecret-key \
  --secret-string='this string is a secret'

and updated aws credentials to be used in config/credentials/kustomization.yaml with valid AWS credentials:

%cat config/credentials/kustomization.yaml
resources:
# - credentials-gsm.yaml
- credentials-asm.yaml
# - credentials-dummy.yaml
# - credentials-onepassword.yaml

%cat config/credentials/credentials-asm.yaml
...
credentials.json: |-
    {
      "accessKeyID": "AKIA...",
      "secretAccessKey": "cmFuZG9tS2VZb25Eb2Nz...",
      "sessionToken": "" 
    }

and an SecretStore resource definition like this one:

% cat config/samples/store_v1alpha1_secretstore.yaml
apiVersion: store.externalsecret-operator.container-solutions.com/v1alpha1
kind: SecretStore
metadata:
  name: secretstore-sample
spec:
  controller: staging
  store:
    type: asm
    auth: 
      secretRef: 
        name: externalsecret-operator-credentials-asm
    parameters:
      region: eu-west-2

and an ExternalSecret resource definition like this one:

% cat config/samples/secrets_v1alpha1_externalsecret.yaml
apiVersion: secrets.externalsecret-operator.container-solutions.com/v1alpha1
kind: ExternalSecret
metadata:
  name: externalsecret-sample
spec:
  storeRef: 
    name: externalsecret-operator-secretstore-sample
  data:
    - key: example-externalsecret-key
      version: latest

The operator fetches the secret from AWS Secrets Manager and injects it as a secret:

% make install
% make deploy
% kubectl get secret externalsecret-operator-externalsecret-sample -n externalsecret-operator-system \
  -o jsonpath='{.data.example-externalsecret-key}' | base64 -d
this string is a secret

Architecture

In this article you can find more information about the architecture and design choices.

Here's a high-level diagram of how things are put together.

CRDs Spec

• See the CRD spec
  • ExternalSecret
  • SecretStore

Supported Backends

We would like to support as many backends as possible and it should be rather easy to write new ones. Currently supported or planned backends are:

• AWS Secrets Manager
• 1Password
• Keybase
• Git-secret
• GCP Secret Manager

1Password [REVIEWING]

Prerequisites

• An existing 1Password team account.
• A 1Password account specifically for the operator. Tip: Setup an email with the + convention: john.doe+operator@example.org
• Store the secret key, master password, email and url of the operator account in your existing 1Password account. This screenshot shows which fields should be used to store this information.
• Our naming convention for the item account is 'External Secret Operator' concatenated with name of the Kubernetes cluster for instance 'External Secret Operator minikube'. This item name is also used for development.

• Install CRDs

  make install

Deployment

• Uncomment and update credentials to be used in config/credentials/kustomization.yaml:

resources:
# - credentials-gsm.yaml
# - credentials-asm.yaml
# - credentials-dummy.yaml
- credentials-onepassword.yaml

• Update the onepassword credentials config/credentials/credentials-onepassword.yaml with valid secretKey and masterPassword

%cat config/credentials/credentials-onepassword.yaml
...
credentials.json: |-
    {
      "secretKey": "${OP_SECRET_KEY}",
      "masterPassword": "${OP_MASTER_PASSWORD}"
    }

• Update the SecretStore resource definition config/samples/store_v1alpha1_secretstore.yaml

% cat  `config/samples/store_v1alpha1_secretstore.yaml
apiVersion: store.externalsecret-operator.container-solutions.com/v1alpha1
kind: SecretStore
metadata:
  name: secretstore-sample
spec:
  controller: staging
  store:
    type: onepassword
    auth: 
      secretRef: 
        name: externalsecret-operator-credentials-onepassword
    parameters:
      vault: Personal
      email: email@email-provider.com
      domain: domain.onepassword.com

• Update the ExternalSecret resource definition config/samples/secrets_v1alpha1_externalsecret.yaml

% cat config/samples/secrets_v1alpha1_externalsecret.yaml
apiVersion: secrets.externalsecret-operator.container-solutions.com/v1alpha1
kind: ExternalSecret
metadata:
  name: externalsecret-sample
spec:
  storeRef: 
    name: externalsecret-operator-secretstore-sample
  data:
    - key: example-externalsecret-key
      version: latest

• The operator fetches the secret from 1password and injects it as a secret:

% make deploy
% kubectl get secret externalsecret-operator-externalsecret-sample -n externalsecret-operator-system \
  -o jsonpath='{.data.example-externalsecret-key}' | base64 -d

GCP Secret Manager

Prerequisites

• Enabled and configured secret manager API on your GCP project. Secret Manager Docs

• Install CRDs

  make install

Deployment

• Uncomment and update credentials to be used in config/credentials/kustomization.yaml:

resources:
- credentials-gsm.yaml
# - credentials-asm.yaml
# - credentials-dummy.yaml
# - credentials-onepassword.yaml

• Update the gsm credentials config/credentials/credentials-gsm.yaml with service account key JSON

%cat config/credentials/credentials-gsm.yaml
...
credentials.json: |-
    {
      "type": "service_account"
      ....
    }

• Update the SecretStore resource definition config/samples/store_v1alpha1_secretstore.yaml

% cat  `config/samples/store_v1alpha1_secretstore.yaml
apiVersion: store.externalsecret-operator.container-solutions.com/v1alpha1
kind: SecretStore
metadata:
  name: secretstore-sample
spec:
  controller: staging
  store:
    type: gsm
    auth: 
      secretRef: 
        name: externalsecret-operator-credentials-gsm
    parameters:
      projectID: external-secrets-operator

• Update the ExternalSecret resource definition config/samples/secrets_v1alpha1_externalsecret.yaml

% cat config/samples/secrets_v1alpha1_externalsecret.yaml
apiVersion: secrets.externalsecret-operator.container-solutions.com/v1alpha1
kind: ExternalSecret
metadata:
  name: externalsecret-sample
spec:
  storeRef: 
    name: externalsecret-operator-secretstore-sample
  data:
    - key: example-externalsecret-key
      version: latest

• The operator fetches the secret from GCP Secret Manager and injects it as a secret:

% make install
% make deploy
% kubectl get secret externalsecret-operator-externalsecret-sample -n externalsecret-operator-system \
  -o jsonpath='{.data.example-externalsecret-key}' | base64 -d

Contributing

Yay! We welcome and encourage contributions to this project!

See our contributing document and Issues for planned improvements and additions.