# External Secrets Documentation Index

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

## 📚 Documentation Files

### [USAGE.md](./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](./templates-examples/secretstore-vault.yaml)**
  - Connect to a Vault backend
  - Use this for most applications that use Vault

- **[secretstore-kubernetes.yaml](./templates-examples/secretstore-kubernetes.yaml)**
  - Sync secrets from another Kubernetes namespace
  - Use this if your secrets are already in Kubernetes

- **[clustersecretstore-vault.yaml](./templates-examples/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](./templates-examples/externalsecret-basic.yaml)**
  - Sync individual secret properties from Vault
  - Most common use case
  - Recommended for most applications

- **[externalsecret-extract.yaml](./templates-examples/externalsecret-extract.yaml)**
  - Sync entire secret objects from Vault
  - Use when you have a secret with many properties

- **[externalsecret-advanced.yaml](./templates-examples/externalsecret-advanced.yaml)**
  - Advanced templating and transformations
  - Build configuration files from secret values
  - Use for complex secret combinations

### Application Integration Templates

- **[deployment-example.yaml](./templates-examples/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](./templates-examples/QUICKSTART.md)**
  - Step-by-step guide to get started quickly
  - Copy-paste commands
  - Verification steps

---

## 🚀 Quick Start Workflow

1. **Read [USAGE.md](./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](./templates-examples/QUICKSTART.md)** to apply and verify

---

## 📋 Common Use Cases

### I want to sync database credentials
→ Copy [secretstore-vault.yaml](./templates-examples/secretstore-vault.yaml) and [externalsecret-basic.yaml](./templates-examples/externalsecret-basic.yaml)

### I want to sync TLS certificates
→ Copy [externalsecret-basic.yaml](./templates-examples/externalsecret-basic.yaml) and set `refreshInterval: 720h` (30 days)

### I want to sync multiple related secrets as a config file
→ Copy [externalsecret-advanced.yaml](./templates-examples/externalsecret-advanced.yaml)

### I want to use a cluster-wide SecretStore
→ Work with the infrastructure team to set up [clustersecretstore-vault.yaml](./templates-examples/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](https://external-secrets.io/)
- [Vault Backend Provider](https://external-secrets.io/latest/provider/vault/)
- [Kubernetes Backend Provider](https://external-secrets.io/latest/provider/kubernetes/)
- [API Reference](https://external-secrets.io/latest/api/secretstore/)

---

## ❓ 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](./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