Secret manager env

[ntner]

What is the feature/update/fix?

Feature: AWS Secrets Manager environment injection

This release adds an optional path for injecting application environment variables into ECS tasks through native AWS Secrets Manager secrets blocks, instead of fetching them from S3 and decrypting with KMS at runtime. When enabled, ECS resolves each variable at task launch from a single per-app JSON secret named {rack}/{app}, pulling individual keys with the ARN:key:: reference format. With the secret in place, the CONVOX_ENV_KEY, CONVOX_ENV_URL, and CONVOX_ENV_VARS task variables are suppressed, which short-circuits the convox-env S3 fetch so values come straight from Secrets Manager.

The model is write-through: S3 remains the source of truth, and Secrets Manager is a deployment-time overlay populated during convox releases promote. Nothing about the existing release storage changes. Enabling the feature is purely additive and is controlled by a Yes/No rack parameter that defaults to No.

Parameter	Type	Default	Effect
SecretsManagerEnv	String (Yes/No)	No	When Yes, ECS tasks resolve env vars from a per-app Secrets Manager secret at launch instead of the S3 + KMS runtime fetch

The parameter can be set at three levels with the following precedence. The rack-level value is the default for all apps. An app-level value is opt-in only: setting SecretsManagerEnv=Yes on an app turns it on even when the rack default is No, but setting it to No does not turn it off when the rack default is Yes. A params entry in convox.yml overrides both the rack and app values and is the way to disable Secrets Manager for a single app while the rack default is Yes.

Level	How to set	Precedence
Rack	convox rack params set SecretsManagerEnv=Yes	Default for all apps
App	convox apps params set SecretsManagerEnv=Yes -a my-app	Opt-in override, only Yes is honored
convox.yml	params: { SecretsManagerEnv: "Yes" }	Overrides both rack and app

Failures are handled without blocking deploys. If the Secrets Manager write fails during a promote, the rack logs a warning and falls back to S3 injection for that release. One-off tasks started with convox run also use Secrets Manager when it is enabled, and fall back to S3 if the secret lookup fails. On app deletion, the per-app secret is scheduled for deletion with a 30-day recovery window. IAM access is scoped tightly: the rack API role gets full Secrets Manager CRUD over the {rack}/* prefix, while app and service execution roles get GetSecretValue only on the exact secret ARN. Gen1 apps are not affected, since they use a separate promote path.

---

How to use it?

Enable Secrets Manager injection for every app on the rack:

convox rack params set SecretsManagerEnv=Yes

Then promote a release so the secret is populated and the task definitions pick up the change:

convox releases promote -a my-app

To keep the rack default off but enable it for one app only:

convox apps params set SecretsManagerEnv=Yes -a my-app
convox releases promote -a my-app

To pin the value per app from source control, add a params block to convox.yml. This overrides both the rack and app settings:

params:
  SecretsManagerEnv: "Yes"

To disable Secrets Manager for a single app while the rack default is Yes, use the convox.yml params block (an app-level No will not turn it off):

params:
  SecretsManagerEnv: "No"

Check your current rack value at any time:

convox rack params | grep SecretsManagerEnv

---

Does it have a breaking change?

No. The feature is entirely additive and off by default. SecretsManagerEnv defaults to No, so racks and apps that take no action behave exactly as before, fetching env vars from S3 and decrypting with KMS at runtime. No CloudFormation resources are renamed, no stack Outputs are removed or renamed, and no existing parameters change type or default.

The change is downgrade safe. Racks running a version without the SecretsManagerEnv parameter silently treat it as No, and the CloudFormation template guards produce no Secrets Manager output when the secret ARN is empty. If a Secrets Manager write ever fails during a promote, the deploy is not blocked: the rack logs a warning and falls back to S3 injection for that release.

---

Requirements

To use this feature, you must update to rack version 20260531001024 or newer.

• Check your rack's version with convox rack
• Update your rack with convox rack update