Skip to content
Pricing

Operate / Automatic renewal

Keep the installed entitlement current.

An optional scheduled helper installs a verified renewed token and refreshes the controller in your AWS account. Available from controller v0.4.0 and module 0.4.0. Billing and the controller’s local entitlement checks keep their existing behavior.

Enable the helper

Upgrade your installation to the matching controller and module from the release manifest. The current pair is v0.7.0 and module 0.7.0.

  1. Store your retained activation key as a raw string in its own Secrets Manager secret. Keep the signed entitlement in its existing separate raw-string secret.
  2. Merge these settings into your module, replacing the example ARNs. Keep entitlement enforcement, DynamoDB coordination, and your pinned public verification key enabled.
  3. Review and apply the Terraform or OpenTofu plan. Enablement performs a normal controller handoff and adds the helper, timer, permissions, and alarms.
entitlement_renewal_enabled    = true
renewal_activation_secret_arn = "arn:aws:secretsmanager:us-east-1:123456789012:secret:gondola/activation-ABC123"
entitlement_secret_arn        = "arn:aws:secretsmanager:us-east-1:123456789012:secret:gondola/entitlement-DEF456"
alarm_action_arns             = ["arn:aws:sns:us-east-1:123456789012:gondola-operations"]

Secrets must be in the controller’s AWS account and region. Pass only their ARNs to Terraform; keep token and activation-key values out of state, command arguments, logs, and support requests. SSM secrets, JSON-key selectors, and version-pinned secret references use the manual renewal procedure.

For customer-managed encryption, set renewal_activation_kms_key_arn and/or renewal_entitlement_kms_key_arn. The controller execution role also needs its entitlement key in secret_kms_key_arns. Your secret and KMS resource policies must permit the corresponding roles.

How renewal runs

EventBridge Scheduler starts a separate 256 CPU-unit / 512 MiB Fargate task every six hours, with up to 15 minutes of scheduling flexibility. It uses the controller’s pinned image and network. Allow HTTPS egress to https://gondola.build/api/entitlements/activate and the required AWS APIs. The helper has its own scoped role and receives no GitHub credentials. AWS task, scheduling, secret, and log usage is billed to your account.

Within seven days of signed expiry, the helper requests a token and verifies its signature, license, organization, and later expiry against your configured verification keys. Unchanged expiry causes no update. A successful renewal promotes the existing secret and rolls the same controller task definition, then waits for readiness under the new token. Running tasks do not reread changed secret values in place.

Manual renewal remains the default. Immediate mid-period plan changes still use a manual refresh. The helper applies verified coverage; it does not extend unpaid coverage or change expiry enforcement.

Monitor and recover

Inspect the renewal stream in your module’s CloudWatch log group. Completion statuses are renewed, not_due, no_later_expiry, and rollout_reconciled. The module adds failed-check and missing-success alarms; configure working alarm_action_arnsto receive them. A missing-success alarm can fire during initial setup before the first check.

Run the returned renewal_task_definition_arn once through ECS to confirm your deployment’s permissions and readiness. After an interrupted update, the next helper reconciles the installed token before requesting another one. Avoid overlapping manual secret writes, Terraform changes, and renewal tasks. Investigate repeated failures before expiry; a helper failure does not roll back to older coverage.

For the complete role, verification-key, CLI, and recovery reference, use docs/operations/entitlement-renewal.md in the signed operator-guide bundle described on the release page. Set entitlement_renewal_enabled = false to remove the helper and return to the manual procedure; the installed secret remains.