159 lines
5.7 KiB
Markdown
159 lines
5.7 KiB
Markdown
# 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
|