Overview - External Secrets Operator

Skip to content

You're not viewing the latest version.

Click here to go to latest.

Initializing search

External Secrets Operator

Behavior

Roles and responsibilities

Access Control

Running multiple Controller

Glossary

Prerequisites

Getting started

FAQ

Stability and Support

Deprecation Policy

API

Generators

Reference Docs

Guides

Kubernetes Secret Types

Lifecycle: ownership & deletion

Decoding Strategies

Controller Classes

Targeting Custom Resources

Generators

Push Secrets

Operations

Tooling

Provider

Examples

Community

External Resources

Behavior

Roles and responsibilities

Access Control

Running multiple Controller

API Overview

Architecture

The External Secrets Operator extends Kubernetes with Custom<br>Resources,<br>which define where secrets live and how to synchronize them. The controller<br>fetches secrets from an external API and creates Kubernetes<br>secrets. If the<br>secret from the external API changes, the controller will reconcile the state in<br>the cluster and update the secrets accordingly.

Resource model

To understand the mechanics of the operator let's start with the data model. The<br>SecretStore references a bucket of key/value pairs. But because every external<br>API is slightly different this bucket may be e.g. an instance of an Azure<br>KeyVault or a AWS Secrets Manager in a certain AWS Account and region. Please<br>take a look at the provider documentation to see what the Bucket actually maps<br>to.

SecretStore

The idea behind the SecretStore resource is to separate concerns of<br>authentication/access and the actual Secret and configuration needed for<br>workloads. The ExternalSecret specifies what to fetch, the SecretStore specifies<br>how to access. This resource is namespaced.

apiVersion: external-secrets.io/v1<br>kind: SecretStore<br>metadata:<br>name: secretstore-sample<br>spec:<br>provider:<br>aws:<br>service: SecretsManager<br>region: us-east-1<br>auth:<br>secretRef:<br>accessKeyIDSecretRef:<br>name: awssm-secret<br>key: access-key<br>secretAccessKeySecretRef:<br>name: awssm-secret<br>key: secret-access-key

The SecretStore contains references to secrets which hold credentials to<br>access the external API.

ExternalSecret

An ExternalSecret declares what data to fetch. It has a reference to a<br>SecretStore which knows how to access that data. The controller uses that<br>ExternalSecret as a blueprint to create secrets.

apiVersion: external-secrets.io/v1<br>kind: ExternalSecret<br>metadata:<br>name: example<br>spec:<br>refreshInterval: 1h0m0s<br>secretStoreRef:<br>name: secretstore-sample<br>kind: SecretStore<br>target:<br>name: secret-to-be-created<br>creationPolicy: Owner<br>data:<br>- secretKey: secret-key-to-be-managed<br>remoteRef:<br>key: provider-key<br>version: provider-key-version<br>property: provider-key-property<br>dataFrom:<br>- extract:<br>key: remote-key-in-the-provider

ClusterSecretStore

The ClusterSecretStore is a global, cluster-wide SecretStore that can be<br>referenced from all namespaces. You can use it to provide a central gateway to your secret provider.

Behavior

The External Secret Operator (ESO for brevity) reconciles ExternalSecrets in<br>the following manner:

ESO uses spec.secretStoreRef to find an appropriate SecretStore. If it<br>doesn't exist or the spec.controller field doesn't match it won't further<br>process this ExternalSecret.

ESO instantiates an external API client using the specified credentials from<br>the SecretStore spec.

ESO fetches the secrets as requested by the ExternalSecret, it will decode<br>the secrets if required

ESO creates an Kind=Secret based on the template provided by<br>ExternalSecret.target.template. The Secret.data can be templated using<br>the secret values from the external API.

ESO ensures that the secret values stay in sync with the external API

Roles and responsibilities

The External Secret Operator is designed to target the following persona:

Cluster Operator : The cluster operator is responsible for setting up the<br>External Secret Operator, managing access policies and creating<br>ClusterSecretStores.

Application developer : The Application developer is responsible for<br>defining ExternalSecrets and the application configuration

Each persona will roughly map to a Kubernetes RBAC role. Depending on your<br>environment these roles can map to a single user. Note: There is no Secret<br>Operator that handles the lifecycle of the secret, this is out of the scope of<br>ESO.

Access Control

The External Secrets Operator runs as a deployment in your cluster with elevated<br>privileges. It will create/read/update secrets in all namespaces and has access<br>to secrets stored in some external API. Ensure that the credentials you provide<br>give ESO the least privilege necessary.

Design your SecretStore/ClusterSecretStore carefully! Be sure to restrict<br>access of application developers to read only certain<br>keys in a shared environment.

You should also consider using Kubernetes' admission control system (e.g.<br>OPA or Kyverno) for<br>fine-grained access control.

Running multiple Controller

You can run multiple controllers within the...