# External Secrets Operator

External Secrets Operator (ESO) is a Kubernetes-native controller that allows you to securely sync secrets from external secret management systems—like AWS Secrets Manager, HashiCorp Vault, Azure Key Vault, and others—into Kubernetes as native Secret resources. It acts as a bridge between Kubernetes and secret providers, ensuring that sensitive data is not hardcoded or manually managed within the cluster.

---

## History

ESO evolved from the earlier Kubernetes External Secrets project, which was limited in flexibility and extensibility. ESO was redesigned using the Kubernetes controller-runtime framework, introducing Custom Resource Definitions (CRDs) such as `ExternalSecret`, `SecretStore`, and `ClusterSecretStore`. This shift enabled better integration, automation, and scalability across different cloud environments and secret backends.

---

## Why It Matters

Managing secrets securely is critical in any production environment. Kubernetes’ native secrets are stored in etcd and, by default, are only base64-encoded—not encrypted. ESO solves this by allowing secrets to live in purpose-built external secret managers, which offer:

- Encryption at rest and in transit
- Role-based access control (RBAC)
- Secret versioning and auditing
- Centralized security policies

By integrating external secrets with Kubernetes, ESO helps reduce:

- Secret sprawl and duplication
- Manual synchronization errors
- Exposure of sensitive credentials in source code or CI pipelines

---

### Key Concepts and CRDs

- **ExternalSecret**: Defines which external secret to fetch and how to project it into a Kubernetes `Secret`.
- **SecretStore**: A namespace-scoped reference to an external provider (e.g., Vault, AWS, GCP).
- **ClusterSecretStore**: A cluster-wide version of `SecretStore` used for multi-namespace secret access.

Each `ExternalSecret` is linked to a `SecretStore` or `ClusterSecretStore`, which contains authentication and configuration information for the external secret backend.

---

### How It Works

1. A `SecretStore` or `ClusterSecretStore` is defined to authenticate with the external secret manager.
2. An `ExternalSecret` CR is created, referencing the store and specifying which secret to retrieve.
3. ESO reads the external secret, applies any defined templates, and creates or updates a native Kubernetes `Secret`.
4. The `Secret` is kept in sync with the external source based on polling intervals or update triggers.

---

### Use Cases

#### ✅ Centralized Secret Management

Use AWS Secrets Manager, Vault, or Azure Key Vault to manage credentials and expose them only at runtime via Kubernetes.

#### ✅ Multi-Cluster Secret Access

Use `ClusterSecretStore` to allow teams to pull shared secrets across multiple namespaces or clusters.

#### ✅ Dynamic Secret Syncing

Automatically propagate secret updates from Vault into your Kubernetes apps without redeploying them.

#### ✅ Least Privilege Principle

Configure ESO to access only specific secrets via IAM policies or Vault roles, enforcing granular security controls.

---

### Example: Using ESO with AWS Secrets Manager

```none
apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: my-db-secret
spec:
  refreshInterval: 1h
  secretStoreRef:
    name: aws-secrets
    kind: SecretStore
  target:
    name: my-db-secret
    creationPolicy: Owner
  data:
    - secretKey: username
      remoteRef:
        key: prod/db-credentials
        property: username
    - secretKey: password
      remoteRef:
        key: prod/db-credentials
        property: password
```

This configuration pulls a username and password from AWS Secrets Manager and stores them as a Kubernetes Secret named `my-db-secret`.

---

### Benefits

- Eliminates secret duplication across environments
- Enforces separation of duties between DevOps and security teams
- Seamlessly integrates with GitOps and CI/CD workflows
- Supports templating and transformation of secret values

---

### Challenges

- Requires proper IAM and backend configuration
- Polling-based sync may delay secret rotation unless carefully tuned
- Secrets still reside in Kubernetes memory and can be accessed by privileged users if not protected

---

### Supported Providers

- AWS Secrets Manager
- HashiCorp Vault
- Azure Key Vault
- Google Secret Manager
- IBM Cloud Secrets Manager
- Akeyless, 1Password, and more

---

### Related Tools

- **Vault Agent Injector**: Sidecar that injects secrets into pods directly from Vault.
- **Sealed Secrets**: Encrypt secrets for safe storage in Git.
- **SOPS + Kustomize**: Manage secrets in encrypted Git files.

---