Secrets Management

Secrets management in Expanso Edge encompasses multiple layers of security, from initial agent registration to runtime pipeline configuration. This guide covers best practices for handling credentials across different deployment environments.

Architecture Overview

Expanso Edge uses secrets at three distinct layers:

1. Bootstrap Secrets

Purpose: Initial agent registration and authentication with Expanso Cloud.

When used: During edge agent startup to establish trust and register the node.

Common approaches:

• Local files with restricted permissions
• Environment variables in systemd services
• Docker/Kubernetes native secret stores

Learn more: Bootstrapping Secrets →

---

2. Pipeline Configuration Secrets

Purpose: Runtime credentials for data sources, destinations, and processors.

When used: When pipelines connect to databases, APIs, message queues, or other authenticated services.

Common approaches:

• Environment variable interpolation (${VAR_NAME})
• Local files mounted into containers
• Dynamic secrets fetched at runtime

Learn more: Local Secrets →

---

3. External Secret Management

Purpose: Centralized, auditable secret storage with rotation and access control.

When used: Production deployments requiring compliance, audit trails, and automated rotation.

Common approaches:

• HashiCorp Vault
• AWS Secrets Manager
• Azure Key Vault
• Google Secret Manager
• Kubernetes CSI Secret Store Driver

Learn more: External Secret Managers →

---

Security Principles

All secret management approaches should follow these principles:

1. Never Hard-Code Secrets

• Don't commit secrets to version control
• Use .env files locally and add to .gitignore
• Reference secrets via environment variables or files

2. Restrict Access

• Use file permissions (e.g., chmod 600) for local files
• Limit service account permissions in Kubernetes
• Apply least-privilege IAM roles in cloud environments

3. Enable Auditability

• Log secret access (but not values)
• Use centralized secret stores for audit trails
• Track which pipelines use which credentials

4. Rotate Regularly

• Implement automated rotation schedules
• Update secrets without redeploying pipelines
• Monitor for expiring credentials

5. Separate Concerns

• Use different credentials per environment (dev/staging/prod)
• Isolate secrets by pipeline or application
• Don't reuse bootstrap tokens across agents

---

Secret Types Reference

Secret Type	Example Use Case	Recommended Storage
Bootstrap Token	Agent registration	Local file, K8s Secret, Docker Secret
Database Password	PostgreSQL connection	Environment variable, Vault
API Key	HTTP output authentication	Environment variable, AWS SM
TLS Certificate	Mutual TLS connections	Local file, K8s Secret, mounted volume
OAuth Token	Third-party API access	Vault with TTL, AWS SM
Encryption Key	Data encryption at rest	KMS, Vault Transit

---

Choosing an Approach

For Development/Testing

→ Local Secrets - Simple file-based or environment variable approach

For Production (Small Scale)

→ Bootstrapping + Local Secrets - Native platform secrets (systemd, Docker, K8s)

For Production (Enterprise)

→ External Secret Managers - Centralized, auditable, with rotation

---

Next Steps

• Getting Started? Start with Bootstrapping Secrets to register your first edge agent
• Configuring Pipelines? See Local Secrets for environment variable interpolation
• Production Deployment? Review External Secret Managers for enterprise patterns