helm-external-secrets/design/001-design-crd-v1beta1.md

---
title: External Secrets CRD promotion
version: v1beta1
authors: all of us
creation-date: 2022-feb-08
status: implemented
---

External Secrets Operator CRD

Table of Contents

• External Secrets Operator CRD
  • Table of Contents
  • Summary
  • Motivation
  • Goals
  • Non-Goals
  • Terminology
  • User Definitions
  • User Stories
  • Proposal
  • External Secret
    • Behavior
  • Secret Store

Summary

This is a proposal to design the Promoted ExternalSecrets CRD. This proposal was approved in 16-feb-2022 during our Community Meeting.

Motivation

The project came up to the point to have grown in users and maturity, hence we are starting to drive efforts to bring it to GA. The promotion of the ExternalSecrets CRD to beta is one of this efforts. This design documentation aims to capture some final changes for ExternalSecrets CRD.

Goals

• Define a beta CRD
• Define structure for getting all provider secrets

• Define structure for new templating engine

  Non-Goals

This KEP proposes the CRD Spec and documents the use-cases, not the choice of technology or migration path towards implementing the CRD.

Terminology

• External Secrets Operator ESO: A Application that runs a control loop which syncs secrets
• ESO instance: A single entity that runs a control loop
• Provider: Is a source for secrets. The Provider is external to ESO. It can be a hosted service like Alibaba Cloud SecretsManager, AWS SystemsManager, Azure KeyVault etc
• SecretStore ST: A Custom Resource to authenticate and configure the connection between the ESO instance and the Provider
• ExternalSecret ES: A Custom Resource that declares which secrets should be synced
• Frontend: A sink for the synced secrets, usually a Secret resource
• Secret: Credentials that act as a key to sensitive information

User Definitions

• operator := I manage one or multiple ESO instances
• user := I only create ES, ESO is managed by someone else

User Stories

From that we can derive the following requirements or user stories:

1. As a ESO operator I want to get all the secrets of a given path from a given provider, if the provider supports it
2. As a ESO operator I want to handle templating like it is a natural language, not needing to worry about how it is actually implemented.

Proposal

External Secret

#only changed fields are commented out.
apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: "hello-world"
  labels:
    acme.org/owned-by: "q-team"
  annotations:
    acme.org/sha: 1234

spec:
  secretStoreRef:
    name: secret-store-name
    kind: SecretStore
  refreshInterval: "1h"
  target:
    name: my-secret
    creationPolicy: 'Merge'
    deletionPolicy: 'None' #Possible values are None, Merge, Delete - TBC during implementation.
    template:
      engineVersion: v2 #Defaults to v2 in v1beta1
      type: kubernetes.io/dockerconfigjson 
      metadata:
        annotations: {}
        labels: {}
      data:
        config.yml: |
          endpoints:
          - https://{{ .data.user }}:{{ .data.password }}@api.example.com

      templateFrom:
      - configMap:
          name: alertmanager
          items:
          - key: alertmanager.yaml
  data:
    - secretKey: secret-key-to-be-managed
      remoteRef:
        key: provider-key
        version: provider-key-version
        property: provider-key-property
  dataFrom:
  - extract: #extract all the keys from one given secret
      key: provider-key
      version: provider-key-version
      property: provider-key-property
  - find:
      name:  #find secrets that match a particular pattern
        regexp: .*pattern.*
      tags:  #find secrets that match the following labels/tags
        provider-label: provider-value
status:
  refreshTime: "2019-08-12T12:33:02Z"
  conditions:
  - type: Ready
    status: "True"
    reason: "SecretSynced"
    message: "Secret was synced"
    lastTransitionTime: "2019-08-12T12:33:02Z"

Behavior

ExternalSecrets now will have a different structure for dataFrom, which will allow fetching several provider secrets with only one ExternalSecret definition. It should be possible to fetch secrets based on regular expressions or by a label/tag selector.

If the user desires to rename the secret keys (e.g. because the key name is not a valid secret key name /foo/bar) they should use template functions to produce a mapping.

Secret Store

SecretStore and ClusterSecretStore do not have any changes from v1alpha1.

apiVersion: external-secrets.io/v1beta1
kind: SecretStore
metadata:
  name: example
  namespace: example-ns
spec:
  controller: dev
  retrySettings:
    maxRetries: 5
    retryInterval: "10s"
  provider:
    aws:
      service: SecretsManager
      role: iam-role
      region: eu-central-1
      auth:
        secretRef:
          accessKeyID:
            name: awssm-secret
            key: access-key
          secretAccessKey:
            name: awssm-secret
            key: secret-access-key
    vault:
      server: "https://vault.acme.org"
      path: "secret"
      version: "v2"
      namespace: "a-team"
      caBundle: "..."
      caProvider:
        type: "Secret"
        name: "my-cert-secret"
        key: "cert-key"
      auth:
        tokenSecretRef:
          name: "my-secret"
          namespace: "secret-admin"
          key: "vault-token"
        appRole:
          path: "approle"
          roleId: "db02de05-fa39-4855-059b-67221c5c2f63"
          secretRef:
            name: "my-secret"
            namespace: "secret-admin"
            key: "vault-token"
        kubernetes:
          mountPath: "kubernetes"
          role: "demo"
          serviceAccountRef:
            name: "my-sa"
            namespace: "secret-admin"
          secretRef:
            name: "my-secret"
            namespace: "secret-admin"
            key: "vault"
    gcpsm:
      auth:
        secretRef:
          secretAccessKeySecretRef:
            name: gcpsm-secret
            key: secret-access-credentials
      projectID: myproject
status:
  conditions:
  - type: Ready
    status: "False"
    reason: "ConfigError"
    message: "SecretStore validation failed"
    lastTransitionTime: "2019-08-12T12:33:02Z"