infra/charts/external-secrets/INDEX.md

External Secrets Documentation Index

This folder contains comprehensive documentation and templates for using External Secrets Operator (ESO) across your repositories.

📚 Documentation Files

USAGE.md

Complete usage guide for External Secrets Operator

Covers:

• Overview and architecture
• Getting started with ESO
• How to structure your secrets-reponame folders
• SecretStore configuration (Vault, Kubernetes, etc.)
• Creating ExternalSecret resources
• Real-world examples (Django, PostgreSQL, TLS)
• Troubleshooting guide
• Best practices

Start here if you want to understand how External Secrets works and how to use it in your repository.

---

🗂️ Templates & Examples

Located in the templates-examples/ folder. Copy these to your repository's secrets-<reponame>/ folder and customize them.

SecretStore Templates

• secretstore-vault.yaml

  • Connect to a Vault backend
  • Use this for most applications that use Vault

• secretstore-kubernetes.yaml

  • Sync secrets from another Kubernetes namespace
  • Use this if your secrets are already in Kubernetes

• clustersecretstore-vault.yaml

  • Cluster-wide Vault connection (managed by infrastructure team)
  • Use this for shared secrets available across the cluster

ExternalSecret Templates

• externalsecret-basic.yaml

  • Sync individual secret properties from Vault
  • Most common use case
  • Recommended for most applications

• externalsecret-extract.yaml

  • Sync entire secret objects from Vault
  • Use when you have a secret with many properties

• externalsecret-advanced.yaml

  • Advanced templating and transformations
  • Build configuration files from secret values
  • Use for complex secret combinations

Application Integration Templates

• deployment-example.yaml
  • Show how to use synced secrets in your Deployment
  • Three different methods to reference secrets:
    • Environment variables via envFrom
    • Individual environment variables
    • Mount as files

Getting Started

• QUICKSTART.md
  • Step-by-step guide to get started quickly
  • Copy-paste commands
  • Verification steps

---

🚀 Quick Start Workflow

1. Read USAGE.md to understand the concepts
2. Copy templates from templates-examples/ to your repository's secrets-<reponame>/ folder
3. Customize the templates with your values:
   • Namespace
   • Vault URLs and paths
   • Secret property names
   • Refresh intervals
4. Follow QUICKSTART.md to apply and verify

---

📋 Common Use Cases

I want to sync database credentials

→ Copy secretstore-vault.yaml and externalsecret-basic.yaml

I want to sync TLS certificates

→ Copy externalsecret-basic.yaml and set refreshInterval: 720h (30 days)

I want to sync multiple related secrets as a config file

→ Copy externalsecret-advanced.yaml

I want to use a cluster-wide SecretStore

→ Work with the infrastructure team to set up clustersecretstore-vault.yaml

---

📁 Expected Repository Structure

After following this guide, your repository should have:

my-app-repo/
├── src/
├── k8s/
│   ├── base/
│   ├── overlays/
│   └── secrets-my-app/                    ← Your secrets folder
│       ├── secretstore.yaml               ← Copied and customized
│       ├── externalsecret.yaml            ← Copied and customized
│       └── deployment.yaml                ← References the secret
├── argocd-app.yaml                        ← Points to k8s/
└── README.md

---

🔗 Links

• Official External Secrets Documentation
• Vault Backend Provider
• Kubernetes Backend Provider
• API Reference

---

❓ FAQ

Q: Can I version control my SecretStore and ExternalSecret files?
A: Yes! These files should be in your repository's Git. Only the actual secret values stay in Vault/backend.

Q: How often are secrets synced?
A: Controlled by refreshInterval in the ExternalSecret (default 1h). You can trigger immediate sync using kubectl annotations.

Q: What happens if the secret backend is unavailable?
A: The operator will continue using the last synced secret. Check logs and operator status.

Q: Can multiple applications use the same SecretStore?
A: Yes, if they're in the same namespace. Or use a ClusterSecretStore for cluster-wide access.

Q: How do I rotate secrets?
A: Update the secret in your backend (Vault, etc.). The operator will automatically sync it based on refreshInterval.

---

🆘 Getting Help

1. Check USAGE.md > Troubleshooting section
2. Review your ExternalSecret status: kubectl describe externalsecret <name> -n <namespace>
3. Check operator logs: kubectl logs -n external-secrets deployment/external-secrets
4. Contact your infrastructure team for Vault or cluster-wide SecretStore issues