Cloud Secrets

Overview

Lifecycle integrates with cloud secret providers to securely inject secrets into your ephemeral environments. You can reference secrets directly in your lifecycle.yaml environment variables using a template syntax, and Lifecycle handles the rest.

Supported providers:

• AWS Secrets Manager
• GCP Secret Manager

Configuration

Secret providers are configured in the Lifecycle global_config database table under the secretProviders key.

Default Configuration

Both AWS and GCP providers are enabled by default. The ClusterSecretStore created by your platform team determines which provider actually works in your cluster.

• On AWS (EKS): Use {{aws:path:key}} syntax. The aws-secretsmanager ClusterSecretStore handles the request.
• On GCP (GKE): Use {{gcp:path:key}} syntax. The gcp-secretmanager ClusterSecretStore handles the request.

If you reference a provider that doesn’t have a ClusterSecretStore in your cluster, the secret will fail to sync and a warning will be logged.

Configuration Fields

Syntax

Reference secrets using the following pattern:

Basic Usage

JSON Secrets

For secrets stored as JSON objects, specify the key to extract:

If your AWS secret myapp/rds-credentials contains:

Your pod will receive:

• DB_USERNAME=admin
• DB_PASSWORD=supersecret
• DB_HOST=db.example.com

Plaintext Secrets

For secrets stored as plain strings, omit the key:

Nested JSON

For nested JSON structures, use dot notation:

For a secret containing:

Where Secrets Work

The secret syntax works in all env blocks:

GitHub Services

Docker Services

Webhooks

Mixing Secrets with Template Variables

You can combine cloud secrets with regular template variables in the same env block:

Multiple Providers

Both providers are enabled by default. If your platform team has configured ClusterSecretStores for both AWS and GCP, you can reference secrets from either in the same deployment:

Error Handling

Lifecycle uses a “warn and continue” approach for secret errors:

Best Practices

Use Descriptive Secret Paths

Organize secrets with meaningful paths:

Group Related Secrets

Store related credentials in a single JSON secret:

Then reference individual keys:

Avoid Secrets in Build Logs

Be cautious when using secrets in build-time environment variables, as they may appear in build logs. Prefer injecting secrets at runtime when possible.

Troubleshooting

Secret Not Injected

1. Check the secret exists in AWS Secrets Manager / GCP Secret Manager
2. Verify the path matches exactly (case-sensitive)
3. Check the key name if using JSON secrets
4. Review Lifecycle logs for warnings about missing secrets
5. Verify provider is enabled in global configuration

Syntax Errors

Common syntax mistakes:

Permission Denied

If you see permission errors:

1. Verify the External Secrets Operator has access to the secret path
2. Check IAM policies allow access to the specific secret
3. Contact your platform team if the secret is in a restricted path

Wrong Provider for Cluster

If you use {{gcp:...}} on an AWS cluster (or vice versa), the ExternalSecret will fail to sync because the ClusterSecretStore doesn’t exist. Check Lifecycle logs for warnings like “ClusterSecretStore not found”.

Prerequisites

For cloud secrets to work, your platform team must set up:

The clusterSecretStore value in your Lifecycle config must match the ClusterSecretStore name configured by your platform team.

Related

• Template Variables - Learn about other template syntax
• Webhooks - Using secrets in webhook environment variables