Project: external-secrets (Provisioning / Security & Compliance)
File: overview.md

The External Secrets Operator extends Kubernetes with [Custom Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/), which define where secrets live and how to synchronize them. The controller fetches secrets from an external API and creates Kubernetes . If the secret from the external API changes, the controller will reconcile the state in the cluster and update the secrets accordingly. To understand the mechanics of the operator let's start with the data model. The SecretStore references a bucket of key/value pairs. But because every external API is slightly different this bucket may be e.g. an instance of an Azure KeyVault or a AWS Secrets Manager in a certain AWS Account and region. Please take a look at the provider documentation to see what the Bucket actually maps to. The idea behind the resource is to separate concerns of authentication/access and the actual Secret and configuration needed for workloads. The ExternalSecret specifies what to fetch, the SecretStore specifies how to access. This resource is namespaced. ``` yaml {% include 'basic-secret-store.yaml' %} ``` The `SecretStore` contains references to secrets which hold credentials to access the external API. An declares what data to fetch. It has a reference to a `SecretStore` which knows how to access that data. The controller uses that `ExternalSecret` as a blueprint to create secrets. ``` yaml {% include 'basic-external-secret.yaml' %} ``` The is a global, cluster-wide SecretStore that can be referenced from all namespaces. You can use it to provide a central gateway to your secret provider. The External Secret Operator (ESO for brevity) reconciles `ExternalSecrets` in the following manner: ESO uses `spec.secretStoreRef` to find an appropriate `SecretStore`. If it doesn't exist or the `spec.controller` field doesn't match it won't further process this ExternalSecret. ESO instanciates an external API client using the specified credentials from the `SecretStore` spec. ESO fetches the secrets as requested by the `ExternalSecret`, it will decode the secrets if required ESO creates an `Kind=Secret` based on the template provided by `ExternalSecret.target.template`. The `Secret.data` can be templated using the secret values from the external API. ESO ensures that the secret values stay in sync with the external API The External Secret Operator is designed to target the following persona: Cluster Operator*: The cluster operator is responsible for setting up the External Secret Operator, managing access policies and creating ClusterSecretStores. Application developer*: The Application developer is responsible for defining ExternalSecrets and the application configuration Each persona will roughly map to a Kubernetes RBAC role. Depending on your environment these roles can map to a single user. Note: There is no Secret Operator that handles the lifecycle of the secret, this is out of the scope of ESO. The External Secrets Operator runs as a deployment in your cluster with elevated privileges. It will create/read/update secrets in all namespaces and has access to secrets stored in some external API. Ensure that the credentials you provide give ESO the least privilege necessary. Design your `SecretStore`/`ClusterSecretStore` carefully! Be sure to restrict access of application developers to read only certain keys in a shared environment. You should also consider using Kubernetes' admission control system (e.g. or ) for fine-grained access control. You can run multiple controllers within the cluster. One controller can be limited to only process `SecretStores` with a predefined `spec.controller` field. !!! note "Testers welcome" This is not widely tested. Please help us test the setup and/or document use-cases.