Updates

Hosted vs. Self-Hosted

This page covers self-hosted deployments, where you run Runlayer on your own infrastructure via Terraform or Runlayer Operator. On Runlayer-hosted deployments, Runlayer operates the infrastructure and applies updates for you—no action is required on your side. For hosted update timing and policies, contact support@runlayer.com.

Choose a Release

Runlayer publishes application releases as exact semantic versions in MAJOR.MINOR.PATCH format, such as 1.28.128. Release tags do not include a v prefix. Review the Runlayer changelog before updating. It is the source of available versions, release notes, and breaking changes. On the ECS Terraform module, also read the module changelog for every module version between yours and the target: it lists breaking changes and steps to take before terraform apply.

Use an exact release version in production. Runlayer application images do not use floating latest, major-only, minor-only, or timestamp release tags.

Update Runlayer

ECS + Terraform
Kubernetes + Operator

Set app_version to the exact release you want to deploy:

app_version = "1.28.128"

Keep the AWS credentials from ECS prerequisites available to Terraform and its migration subprocess. For a module upgrade, change the pinned archive version in source and run terraform init -upgrade first. Then review and apply the change:

terraform plan -var-file="production.tfvars"
terraform apply -var-file="production.tfvars"

If you omit app_version, the module uses the application version pinned by that module release. Set app_version when you want to update the application independently of the infrastructure module.app_version and ecr_repositories are mutually exclusive. If you provide your own images, update all three entries to exact tags or digests instead:

ecr_repositories = {
  backend  = "123456789012.dkr.ecr.us-east-1.amazonaws.com/runlayer/backend:1.28.128"
  frontend = "123456789012.dkr.ecr.us-east-1.amazonaws.com/runlayer/frontend:1.28.128"
  worker   = "123456789012.dkr.ecr.us-east-1.amazonaws.com/runlayer/worker:1.28.128"
}

Pin the application version and all application images in your RunlayerInstance values:

spec:
  version: "1.28.128"
  images:
    backend: REGISTRY/runlayer/backend:1.28.128
    frontend: REGISTRY/runlayer/frontend:1.28.128
    worker: REGISTRY/runlayer/worker:1.28.128

Apply the instance chart with your existing values:

helm upgrade --install tenant infra/aws-helm/runlayer-instance \
  --namespace runlayer-system \
  -f runlayer-instance-values.yaml

The operator runs migrations with the backend image before rolling out workloads.Bumping an optional component’s own image (e.g. components.extendDB.image) is a separate, per-component concern — see Upgrading and recovering ExtendDB.

During an update, Runlayer runs database migrations before rolling out the application services. ECS and Kubernetes replace workloads gradually and use health checks to determine readiness.

Monitor an Update

ECS
Kubernetes

Run from the root configuration directory with the AWS profile and region used for deployment. These commands use the root outputs in the ECS deployment guide. For older configurations, export those outputs or substitute your actual cluster and log-group names.

aws ecs describe-services \
  --cluster "$(terraform output -raw ecs_cluster_name)" \
  --services backend-service frontend-service

aws elbv2 describe-target-health \
  --target-group-arn "REPLACE_WITH_TARGET_GROUP_ARN"

aws logs tail "$(terraform output -raw backend_log_group_name)" --follow

kubectl rollout status deployment/anysource-backend -n anysource
kubectl rollout status deployment/anysource-frontend -n anysource
kubectl get pods -n anysource

After the rollout, verify the backend health endpoint and key user workflows:

curl https://your-domain.com/api/v1/utils/health-check/

Roll Back

Review the release notes before rolling back. A release may include database migrations that are not backward-compatible with an older application version.

ECS + Terraform
Kubernetes + Helm

Set app_version to the previous exact release, then review and apply:

app_version = "1.28.127"

terraform plan -var-file="production.tfvars"
terraform apply -var-file="production.tfvars"

Roll back to a previous Helm revision:

helm history anysource -n anysource
helm rollback anysource REPLACE_WITH_REVISION -n anysource --wait --timeout=10m

If you manage image tags separately from chart revisions, restore all three application tags to the same previous release and run helm upgrade again.

If the release changed the database schema incompatibly, restore the matching database snapshot or follow the release-specific rollback instructions before starting the older application version.

Database Safety

Runlayer’s Terraform module and Helm chart run migrations as part of the update workflow. Before a significant update:

Review migration notes in the changelog.
Confirm automated backups and point-in-time recovery are enabled.
Create a manual snapshot when your change policy requires one.
Verify migration completion before troubleshooting application tasks or pods.

Example Aurora snapshot command for project = "ecs", environment = "production" (substitute your actual cluster identifier):

aws rds create-db-cluster-snapshot \
  --db-cluster-identifier aurora-ecs-production-cluster \
  --db-cluster-snapshot-identifier backup-before-update-$(date +%Y%m%d)

Security Updates

For a Runlayer security fix, deploy the exact patched release from the changelog using the same Terraform or Helm process above. Do not retag an image as latest. If you maintain custom images, publish an immutable tag or digest and update every applicable ecr_repositories or Helm image entry explicitly. AWS manages patches for the underlying ECS Fargate, ALB, and VPC services. RDS applies eligible maintenance during its configured maintenance window:

preferred_maintenance_window = "sun:05:00-sun:06:00"

Best Practices

Before Updates

Review release notes and breaking changes
Confirm backups and recovery procedures
Test the exact version in staging
Schedule an appropriate maintenance window

During Updates

Watch migration output
Monitor service or pod readiness
Check application logs and health endpoints
Verify critical user workflows

After Updates

Confirm all services are healthy
Monitor error rates and latency
Verify integrations and MCP traffic
Record any deployment-specific issues

Rollback Readiness

Keep the previous exact version available
Know the previous Helm revision
Check migration compatibility before rollback
Practice recovery procedures

Troubleshooting Updates

Service Won't Start After Update

Check the migration task or job first, then inspect workload events and logs. Common causes include database migration failures, missing secrets, insufficient registry permissions, and health-check failures.

# ECS
aws ecs describe-services \
  --cluster "$(terraform output -raw ecs_cluster_name)" \
  --services backend-service frontend-service

# Kubernetes
kubectl get events -n anysource --sort-by='.lastTimestamp'
kubectl logs deployment/anysource-backend -n anysource

Enable

Control

Self-Hosted Deployment

Operations

Cookbook

Integrations

Connectors

Resources

Hosted vs. Self-Hosted

Choose a Release

Update Runlayer

Monitor an Update

Roll Back

Database Safety

Security Updates

Best Practices

Before Updates

During Updates

After Updates

Rollback Readiness

Troubleshooting Updates

​Hosted vs. Self-Hosted

​Choose a Release

​Update Runlayer

​Monitor an Update

​Roll Back

​Database Safety

​Security Updates

​Best Practices

Before Updates

During Updates

After Updates

Rollback Readiness

​Troubleshooting Updates

Hosted vs. Self-Hosted

Choose a Release

Update Runlayer

Monitor an Update

Roll Back

Database Safety

Security Updates

Best Practices

Troubleshooting Updates