Requirements

Prepare these inputs before applying either AWS composition.

Accounts and tools

  • An AWS account and one primary AWS region.
  • AWS credentials allowed to create the VPC, load balancer, ECS, RDS, ElastiCache, S3, KMS, Secrets Manager, IAM, EC2, Auto Scaling, and optional CloudFront resources in the composition you select.
  • OpenTofu or Terraform, plus the AWS CLI, jq, OpenSSL, and curl. The repository’s Nix development shell provides the pinned project toolchain.
  • A GitHub OAuth app for browser login.
  • A customer-owned ClickHouse service reachable from Control Plane, dispatcher, and migration tasks over HTTPS.

Required deployment inputs

Both infra/aws/quickstart and infra/aws/standard require:

Input Purpose
aws_region Selects regional infrastructure and the release’s worker AMI.
helmr_version Resolves the official AWS release manifest.
region_id Identifies this Helmr region.
worker_group_name Names the initial logical worker group.
platform_store_uri Points to immutable Platform Artifact objects.
platform_store_bucket_arn Authorizes access to the Platform Artifact bucket.
platform_store_kms_key_arn Authorizes decryption of Platform Artifacts.
clickhouse_url HTTPS endpoint for historical telemetry.
github_oauth_client_id Non-secret OAuth application client ID.
worker_network_blocked_ipv4_cidrs Deployment-owned deny set that must wholly cover the execution VPC prefix.

The Platform Artifact values come from infra/aws/modules/release-storage as a child module under an operator-owned root and backend, or from an equivalent deployment. The example compositions do not create that foundation for you. Compose infra/aws/modules/release-publisher separately when you need a publisher role, passing the exact storage outputs and your trusted IAM principals.

Release artifacts

Stable and preview common releases publish a signed release-index.json with CLI, SDK, Control Plane/builder images, and Worker host/runtime bundles. Neither publishes managed AMIs or aws-artifacts.json.

For these releases, supply the AWS compositions’ explicit controlplane_image (digest-pinned from the verified index’s Control Plane descriptor) and worker_ami_id when workers are enabled. Prepare that AMI in your deployment from the selected host/runtime bundles. Selecting helmr_version alone cannot supply those AWS-specific inputs: the generic resolver’s manifest default is not an output of the common release graph. An operator-owned AWS manifest is also an explicit preparation input; it is not a Product publication fallback.

Worker prerequisites

Workers additionally need:

  • Private-subnet outbound access to the Control Plane, S3, ECR, AWS APIs, registries, and any external services tasks call.
  • KVM-capable EC2 capacity. The evaluation profile supports explicitly enabled nested virtualization on supported families; the production profile defaults to a metal instance.
  • A worker AMI containing worker, Firecracker, jailer, ip, nft, AWS CLI v2, curl, the systemd unit, and certified guest boot artifacts.
  • Explicit host, VM, cache, disk, and execution-slot capacity sized for the workload.
  • SSM access for maintenance unless you supply an alternative. The module does not open SSH by default.

Review workers before creating capacity.