hecks 2.5.1 → 2.7.0

data/lib/hecks/projections/deploy/preview/preview.sh.erb

@@ -0,0 +1,446 @@
+#!/usr/bin/env bash
+# GENERATED by bin/project_deploy - re-run it to refresh this file rather than
+# hand-editing. Source: the `preview` block of the domain's deployed_to("AwsFargate").
+#
+# Feature-branch previews of <%= s.infra_name %>: one isolated stack per git branch,
+# named from the branch, no flags to remember.
+#
+#   preview.sh deploy            create or update THIS branch's preview
+#   preview.sh destroy           tear it down again (PREVIEW_DROP_DATABASE=1 also drops its database)
+#   preview.sh list              every preview that exists
+#   preview.sh url               this branch's URL
+#   preview.sh name              what this branch's preview is called (no AWS calls)
+#   preview.sh ensure-database   create this branch's database if it is missing
+<% if s.first_admin -%>
+#   preview.sh login             a browser-console line that signs you in as its first admin
+<% end -%>
+#
+# `deploy` pushes images that are already built locally (<%= image_hint %>), so it deploys
+# your WORKING TREE, not the last commit; the Commit stack tag says which, with -dirty
+# when there are uncommitted changes. Build them first with `make docker-build`.
+#
+# It cannot touch the live stack: it only ever operates on stacks named
+# <%= s.prefix %>-*, it refuses <%= s.protected_branches.join(', ') %>, and preview.yaml is a
+# separate template from template.yaml.
+#
+# Needs: aws, docker, git, curl<% if s.first_admin %>, python3 (for the signup and login tokens)<% end %>.
+set -euo pipefail
+cd "$(dirname "${BASH_SOURCE[0]}")"
+
+REGION="<%= s.region %>"
+OWNER_STACK="<%= s.owner_stack %>"
+DATABASE_STACK="<%= s.database_stack %>"
+DATABASE_ENDPOINT_OUTPUT="<%= s.database_endpoint_output %>"
+DATABASE_SECRET_OUTPUT="<%= s.database_secret_output %>"
+PREFIX="<%= s.prefix %>"
+DB_PREFIX="<%= s.db_prefix %>"
+SERVICES="<%= s.containers.map(&:name).join(' ') %>"
+PROTECTED_BRANCHES="<%= s.protected_branches.join(' ') %>"
+SIGNUP_PATH="<%= s.signup_path %>"
+LANDING_PATH="<%= s.landing_path %>"
+SESSION_COOKIE="<%= s.session_cookie || 'hecks_session' %>"
+
+die() { echo "error: $*" >&2; exit 1; }
+warn() { echo "warning: $*" >&2; }
+
+# The local docker image `deploy` pushes for one container.
+local_image() {
+  case "$1" in
+<% s.containers.each do |c| -%>
+    <%= c.name %>) echo "<%= c.image %>" ;;
+<% end -%>
+    *) die "no local image is declared for '$1'" ;;
+  esac
+}
+
+# The CloudFormation image-tag parameter of one container.
+tag_parameter() {
+  case "$1" in
+<% s.containers.each do |c| -%>
+    <%= c.name %>) echo "<%= c.logical %>ImageTag" ;;
+<% end -%>
+  esac
+}
+
+# ---- naming: everything derives from the branch ---------------------------
+
+# The 5-character hash that keeps two branches from sharing a stack.
+hash5() {
+  printf '%s' "$1" | { shasum 2>/dev/null || sha1sum; } | cut -c1-5
+}
+
+# Lowercase, non-alphanumerics to hyphens. Anything that changed on the way (a
+# slash, an underscore, truncation to the 20 characters the ALB name allows)
+# gets a 5-character hash of the real name, so `feat/x` and `feat-x` cannot land
+# on the same stack. An already-clean short name is used as is.
+derive_env() {
+  local lower slug
+  lower=$(printf '%s' "$1" | tr '[:upper:]' '[:lower:]')
+  slug=$(printf '%s' "$lower" | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//')
+  [ -n "$slug" ] || die "branch name '$1' has no usable characters"
+  if [ "$slug" != "$lower" ] || [ ${#slug} -gt 20 ]; then
+    slug=$(printf '%s' "${slug:0:14}" | sed -E 's/-+$//')-$(hash5 "$1")
+  fi
+  printf '%s' "$slug"
+}
+
+# Sets BRANCH and every name derived from it. Called by the commands that act on
+# one branch's preview (not by `list`, which is branch-independent).
+init_branch() {
+  BRANCH="${BRANCH:-$(git rev-parse --abbrev-ref HEAD)}"
+  [ "$BRANCH" != "HEAD" ] || die "detached HEAD - check out a branch, or pass BRANCH=<name>"
+  local protected
+  for protected in $PROTECTED_BRANCHES; do
+    [ "$BRANCH" != "$protected" ] || die "refusing to make a preview of $BRANCH - the live stack deploys through its own targets"
+  done
+  ENV_NAME=$(derive_env "$BRANCH")
+  STACK="$PREFIX-$ENV_NAME"
+  DB_NAME="${DB_PREFIX}_pv_$(printf '%s' "$ENV_NAME" | tr '-' '_')"
+  CLUSTER="$PREFIX-$ENV_NAME"
+  LOG_GROUP="/ecs/$PREFIX-$ENV_NAME"
+}
+
+# ---- helpers ---------------------------------------------------------------
+
+stack_status() {
+  aws cloudformation describe-stacks --stack-name "$STACK" --region "$REGION" \
+    --query 'Stacks[0].StackStatus' --output text 2>/dev/null || true
+}
+
+stack_output() { # <stack> <OutputKey>
+  aws cloudformation describe-stacks --stack-name "$1" --region "$REGION" \
+    --query "Stacks[0].Outputs[?OutputKey=='$2'].OutputValue" --output text
+}
+
+# A value the owner or database stack must provide.
+owner_output() { # <stack> <OutputKey>
+  local value
+  value=$(stack_output "$1" "$2")
+  { [ -n "$value" ] && [ "$value" != "None" ]; } || die "$1 has no $2 output"
+  printf '%s' "$value"
+}
+
+resolve_owner() {
+  VPC=$(owner_output "$OWNER_STACK" VpcId)
+  SUBNET_A=$(owner_output "$OWNER_STACK" PrivateSubnetAId)
+  SUBNET_B=$(owner_output "$OWNER_STACK" PrivateSubnetBId)
+  PUBLIC_A=$(owner_output "$OWNER_STACK" PublicSubnetId)
+  PUBLIC_B=$(owner_output "$OWNER_STACK" BastionSubnetId)
+  SG=$(owner_output "$OWNER_STACK" FunctionSecurityGroupId)
+  DB_HOST=$(owner_output "$DATABASE_STACK" "$DATABASE_ENDPOINT_OUTPUT")
+  DB_SECRET=$(owner_output "$DATABASE_STACK" "$DATABASE_SECRET_OUTPUT")
+}
+
+# The DesiredCount the stack currently has (0 if there is no stack yet). Kept as
+# is while new images roll in, so a re-run after a failed deploy cannot start
+# tasks before the database exists.
+current_count() {
+  aws cloudformation describe-stacks --stack-name "$STACK" --region "$REGION" \
+    --query "Stacks[0].Parameters[?ParameterKey=='DesiredCount'].ParameterValue" --output text 2>/dev/null \
+    | grep -E '^[0-9]+$' || echo 0
+}
+
+guard_status() {
+  case "$(stack_status)" in
+    ROLLBACK_COMPLETE|CREATE_FAILED|DELETE_FAILED)
+      die "$STACK is in a failed state ($(stack_status)); run 'preview.sh destroy' first, then deploy again" ;;
+  esac
+}
+
+# Only ever operate on preview stacks.
+guard_stack_name() {
+  case "$STACK" in
+    "$PREFIX"-*) ;;
+    *) die "refusing to operate on $STACK: not a preview stack" ;;
+  esac
+}
+
+# stack_deploy <desired-count> <image-tag>
+stack_deploy() {
+  local commit dirty=""
+  commit=$(git rev-parse --short HEAD 2>/dev/null || echo unknown)
+  git diff --quiet HEAD -- 2>/dev/null || dirty="-dirty"
+  local overrides="" svc
+  for svc in $SERVICES; do
+    overrides="$overrides $(tag_parameter "$svc")=$2"
+  done
+  # shellcheck disable=SC2086
+  aws cloudformation deploy --template-file preview.yaml --stack-name "$STACK" --region "$REGION" \
+    --capabilities CAPABILITY_IAM --no-fail-on-empty-changeset \
+    --tags "Project=$PREFIX" "ManagedBy=preview.sh" "Branch=$BRANCH" "Commit=$commit$dirty" \
+    --parameter-overrides \
+      EnvName="$ENV_NAME" DbName="$DB_NAME" \
+      OwningVpcId="$VPC" OwningSubnetAId="$SUBNET_A" OwningSubnetBId="$SUBNET_B" \
+      OwningPublicSubnetAId="$PUBLIC_A" OwningPublicSubnetBId="$PUBLIC_B" \
+      OwningSecurityGroupId="$SG" OwningDatabaseEndpoint="$DB_HOST" OwningDatabaseSecretArn="$DB_SECRET" \
+      DesiredCount="$1" $overrides
+}
+
+# ---- the database ----------------------------------------------------------
+
+# The database instance is reachable only from inside the VPC, so the database is
+# created (or dropped) by a one-shot task from preview.yaml, not from this machine.
+# run_database_task <create|drop>
+run_database_task() {
+  local action="$1" taskdef task code
+  taskdef=$(stack_output "$STACK" DbInitTaskDefinition)
+  task=$(aws ecs run-task --cluster "$CLUSTER" --launch-type FARGATE --task-definition "$taskdef" --region "$REGION" \
+    --overrides "{\"containerOverrides\":[{\"name\":\"dbinit\",\"environment\":[{\"name\":\"ACTION\",\"value\":\"$action\"}]}]}" \
+    --network-configuration "awsvpcConfiguration={subnets=[$SUBNET_A,$SUBNET_B],securityGroups=[$SG],assignPublicIp=DISABLED}" \
+    --query 'tasks[0].taskArn' --output text)
+  { [ -n "$task" ] && [ "$task" != "None" ]; } || die "could not start the database task"
+  aws ecs wait tasks-stopped --cluster "$CLUSTER" --tasks "$task" --region "$REGION"
+  code=$(aws ecs describe-tasks --cluster "$CLUSTER" --tasks "$task" --region "$REGION" \
+    --query 'tasks[0].containers[0].exitCode' --output text)
+  if [ "$code" != "0" ]; then
+    aws logs tail "$LOG_GROUP" --log-stream-name-prefix dbinit --since 15m --region "$REGION" >&2 || true
+    die "database task exited with code $code (log above)"
+  fi
+}
+
+ensure_database() {
+  echo "==> creating database $DB_NAME if it does not exist (one-shot task)"
+  run_database_task create
+}
+
+cmd_ensure_database() {
+  [ -n "$(stack_status)" ] || die "no preview stack $STACK - run 'preview.sh deploy' first"
+  resolve_owner
+  ensure_database
+}
+
+# ---- deploy ----------------------------------------------------------------
+
+cmd_deploy() {
+  local svc
+  for svc in $SERVICES; do
+    docker image inspect "$(local_image "$svc")" >/dev/null 2>&1 \
+      || die "image $(local_image "$svc") is not built - build the images first (make docker-build)"
+  done
+  guard_stack_name
+  guard_status
+  resolve_owner
+
+  local existed=0 tag account ecr
+  [ -n "$(stack_status)" ] && existed=1
+
+  echo "==> preview '$ENV_NAME' for branch '$BRANCH' (stack $STACK, database $DB_NAME)"
+  if [ "$existed" = 0 ]; then
+    echo "==> creating the stack with no tasks running (the ECR repositories must exist before images can be pushed)"
+    stack_deploy 0 bootstrap
+  fi
+
+  tag="$ENV_NAME-$(date -u +%Y%m%d%H%M%S)"
+  account=$(aws sts get-caller-identity --query Account --output text)
+  ecr="$account.dkr.ecr.$REGION.amazonaws.com"
+
+  echo "==> ecr login"
+  # An isolated docker config: Docker Desktop's keychain helper can hang in a
+  # headless shell.
+  local docker_config=.docker-config-no-keychain
+  mkdir -p "$docker_config"
+  echo '{}' > "$docker_config/config.json"
+  aws ecr get-login-password --region "$REGION" | docker --config "$docker_config" login --username AWS --password-stdin "$ecr"
+
+  for svc in $SERVICES; do
+    echo "==> pushing $svc as $tag"
+    docker tag "$(local_image "$svc")" "$ecr/$PREFIX-$ENV_NAME-$svc:$tag"
+    docker --config "$docker_config" push "$ecr/$PREFIX-$ENV_NAME-$svc:$tag"
+  done
+
+  echo "==> pointing the stack at the new images"
+  stack_deploy "$(current_count)" "$tag"
+
+  ensure_database
+
+  echo "==> starting the service"
+  stack_deploy 1 "$tag"
+  echo "==> waiting for the service to settle (a first boot can take several minutes)"
+  aws ecs wait services-stable --cluster "$CLUSTER" --services "$PREFIX-$ENV_NAME" --region "$REGION" \
+    || die "service did not settle in time - check: aws logs tail $LOG_GROUP --follow --region $REGION"
+<% if s.first_admin -%>
+
+  signup_admin
+<% end -%>
+
+  echo
+  echo "Preview is up: $(stack_output "$STACK" PreviewUrl)"
+<% if s.first_admin -%>
+  echo "  sign in:   preview.sh login   (a one-line session for $ADMIN_EMAIL)"
+<% end -%>
+  echo "  logs:      aws logs tail $LOG_GROUP --follow --region $REGION"
+  echo "  tear down: preview.sh destroy"
+}
+<% if s.first_admin -%>
+
+# ---- first admin: sign the deployer up -------------------------------------
+#
+# A brand-new preview has nobody in it, and sign-in checks membership. The way in
+# is the host's own signup: POST <%= s.signup_path %> dispatches the domain's SignUp command,
+# and the domain's translations turn the signup into the first admin in the
+# preview's own database. The credential is a purpose-bound token minted from the
+# preview's session secret, so only someone with AWS access to the account can
+# sign anyone up. It needs a domain image whose host serves the signup route and
+# a domain that attaches the signups chapter; the warnings below say which is missing.
+
+# Who becomes the preview's first admin: the person deploying it. PREVIEW_ADMIN_EMAIL
+# and PREVIEW_ADMIN_NAME override; the default is your git identity.
+admin_identity() {
+  ADMIN_EMAIL="${PREVIEW_ADMIN_EMAIL:-$(git config user.email || true)}"
+  [ -n "$ADMIN_EMAIL" ] || die "no email to sign up as the preview's first admin - set PREVIEW_ADMIN_EMAIL or git config user.email"
+  ADMIN_NAME="${PREVIEW_ADMIN_NAME:-$(git config user.name || true)}"
+  [ -n "$ADMIN_NAME" ] || ADMIN_NAME="${ADMIN_EMAIL%%@*}"
+}
+
+# The preview's own session secret (the stack generates it). Never printed.
+session_secret() {
+  aws secretsmanager get-secret-value --secret-id "$(stack_output "$STACK" SessionSecretArn)" --region "$REGION" \
+    --query SecretString --output text \
+    | python3 -c 'import json,sys; print(json.load(sys.stdin)["session_secret"])'
+}
+
+# The two tokens the host verifies: base64url(payload) + "." + hex HMAC-SHA256.
+# A signup token is bound to its purpose (key "signup:<secret>", good for 10
+# minutes), so a session can never sign anyone up. A session token is the plain
+# account token, keyed with the bare secret (good for 8 hours).
+mint_token() { # <signup|session> <secret> [email]
+  KIND="$1" SECRET="$2" EMAIL="${3:-}" python3 - <<'PY'
+import base64, hashlib, hmac, json, os, time
+
+kind, secret = os.environ["KIND"], os.environ["SECRET"]
+now = int(time.time())
+if kind == "signup":
+    payload, key = {"purpose": "signup", "exp": now + 600}, "signup:" + secret
+else:
+    payload, key = {"email": os.environ["EMAIL"], "exp": now + 8 * 3600}, secret
+encoded = base64.urlsafe_b64encode(json.dumps(payload, separators=(",", ":")).encode()).rstrip(b"=").decode()
+print(encoded + "." + hmac.new(key.encode(), encoded.encode(), hashlib.sha256).hexdigest())
+PY
+}
+
+# Signs the deployer up. Never fatal: a preview without an admin is still worth
+# having, so a problem is a warning that says what is missing. A new distribution
+# and ALB rule can take a few minutes to answer, so connection errors, 403s and
+# 5xxs are retried (up to ~10 minutes); anything else is an answer.
+signup_admin() {
+  admin_identity
+  local url secret body response status attempt=0
+  url=$(stack_output "$STACK" PreviewUrl)
+  secret=$(session_secret)
+  response=$(mktemp)
+  echo "==> signing $ADMIN_EMAIL up as the preview's first admin (POST $url$SIGNUP_PATH)"
+  while :; do
+    body=$(TOKEN="$(mint_token signup "$secret")" EMAIL="$ADMIN_EMAIL" NAME="$ADMIN_NAME" python3 -c \
+      'import json, os; print(json.dumps({"token": os.environ["TOKEN"], "email": os.environ["EMAIL"], "name": os.environ["NAME"]}))')
+    status=$(curl -s -o "$response" -w '%{http_code}' --max-time 30 -X POST -H 'Content-Type: application/json' -d "$body" "$url$SIGNUP_PATH" || true)
+    status="${status:-000}"
+    case "$status" in
+      201)
+        echo "    signed up"; rm -f "$response"; return 0 ;;
+      422)
+        if grep -q '"AlreadyExists"' "$response"; then
+          echo "    already signed up"
+        else
+          warn "the domain refused the signup: $(cat "$response")"
+          warn "does this domain attach the signups chapter?"
+        fi
+        rm -f "$response"; return 0 ;;
+      302|404)
+        warn "this domain has no POST $SIGNUP_PATH route (HTTP $status) - build the domain image from a host that serves it and redeploy"
+        rm -f "$response"; return 0 ;;
+      400|401)
+        warn "the domain refused the signup (HTTP $status): $(cat "$response")"
+        rm -f "$response"; return 0 ;;
+      *)
+        attempt=$((attempt + 1))
+        if [ "$attempt" -ge 40 ]; then
+          warn "the preview never answered POST $SIGNUP_PATH (last HTTP $status) - run 'preview.sh deploy' again once it is up"
+          rm -f "$response"; return 0
+        fi
+        sleep "${PREVIEW_SIGNUP_RETRY_SECONDS:-15}" ;;
+    esac
+  done
+}
+
+# Prints what to paste into the browser console to sign in as the preview's first
+# admin: a session for that email signed with THIS preview's session secret (the
+# secret itself is never printed). Anyone with AWS access to the account could
+# mint the same, which is the point: it is the deployer's door, not a public one.
+cmd_login() {
+  [ -n "$(stack_status)" ] || die "no preview for branch '$BRANCH' - run 'preview.sh deploy'"
+  admin_identity
+  local url token
+  url=$(stack_output "$STACK" PreviewUrl)
+  token=$(mint_token session "$(session_secret)" "$ADMIN_EMAIL")
+  echo "Signing in to $url as $ADMIN_EMAIL (good for 8 hours)"
+  echo
+  echo "1. Open $url$LANDING_PATH"
+  echo "2. In the browser console (developer tools), run:"
+  echo
+  echo "   document.cookie = \"$SESSION_COOKIE=$token; path=/; Secure; SameSite=Lax\""
+  echo
+  echo "3. Reload the page"
+}
+<% end -%>
+
+# ---- destroy ---------------------------------------------------------------
+
+cmd_destroy() {
+  guard_stack_name
+  [ -n "$(stack_status)" ] || die "no preview stack $STACK (nothing to destroy)"
+  if [ "${PREVIEW_DROP_DATABASE:-}" = "1" ]; then
+    resolve_owner
+    echo "==> dropping database $DB_NAME (one-shot task; PREVIEW_DROP_DATABASE=1)"
+    run_database_task drop
+  fi
+  echo "==> deleting $STACK"
+  aws cloudformation delete-stack --stack-name "$STACK" --region "$REGION"
+  aws cloudformation wait stack-delete-complete --stack-name "$STACK" --region "$REGION"
+  if [ "${PREVIEW_DROP_DATABASE:-}" = "1" ]; then
+    echo "Deleted, and the database $DB_NAME is dropped."
+  else
+    echo "Deleted. The database $DB_NAME is left on the shared instance on purpose, so a later"
+    echo "deploy of this branch picks its data back up. Set PREVIEW_DROP_DATABASE=1 to drop it."
+  fi
+}
+
+# ---- list / url / name -----------------------------------------------------
+
+cmd_list() {
+  aws cloudformation describe-stacks --region "$REGION" \
+    --query "Stacks[?starts_with(StackName, '$PREFIX-')].[StackName, StackStatus, Tags[?Key=='Branch']|[0].Value, Tags[?Key=='Commit']|[0].Value, Outputs[?OutputKey=='PreviewUrl']|[0].OutputValue]" \
+    --output table
+}
+
+cmd_url() {
+  [ -n "$(stack_status)" ] || die "no preview for branch '$BRANCH' - run 'preview.sh deploy'"
+  stack_output "$STACK" PreviewUrl
+}
+
+# What this branch's preview is (or would be) called - no AWS calls.
+cmd_name() {
+  echo "branch:   $BRANCH"
+  echo "env:      $ENV_NAME"
+  echo "stack:    $STACK"
+  echo "database: $DB_NAME"
+}
+
+main() {
+  case "${1:-}" in
+    deploy)          init_branch; cmd_deploy ;;
+    destroy)         init_branch; cmd_destroy ;;
+    ensure-database) init_branch; cmd_ensure_database ;;
+    list)            cmd_list ;;
+    url)             init_branch; cmd_url ;;
+    name)            init_branch; cmd_name ;;
+<% if s.first_admin -%>
+    login)           init_branch; cmd_login ;;
+<% end -%>
+    *) die "usage: preview.sh <deploy|destroy|ensure-database|list|url|name<%= '|login' if s.first_admin %>>" ;;
+  esac
+}
+
+# Sourcing this file (to reuse its functions) does not run a command.
+if [ "${BASH_SOURCE[0]}" = "$0" ]; then
+  main "$@"
+fi

data/lib/hecks/projections/deploy/preview/routing_yaml.rb

@@ -0,0 +1,216 @@
+require "json"
+require_relative "yaml_text"
+
+module Hecks
+  module Projections
+    module Deploy
+      module Preview
+        # The network edge of a preview stack: security groups, target groups, the
+        # load balancer, its listener rules and the service that registers the containers.
+        #
+        # A container is reachable when it is the default or owns a path. Paths are
+        # split into rules of at most five, the most a load balancer condition holds.
+        module RoutingYaml
+          CLOUDFRONT_PREFIX_LIST = "pl-3b927c52".freeze
+          PATHS_PER_RULE = 5
+          INGRESS_NOTE = <<~NOTE.chomp.freeze
+            # One ingress rule per routed container on the shared owner security group, removed
+            # with the stack. The group has a rules-per-group quota, so delete stale previews.
+          NOTE
+
+          extend YamlText
+
+          module_function
+
+          # Renders the load balancer's security group and one ingress rule per routed container.
+          #
+          # @param settings [Settings] the resolved preview settings
+          # @return [Array<String>] the resource blocks
+          def networking(settings)
+            ingress = settings.containers.select(&:routed?).map do |c|
+              <<~YAML.chomp
+                ComputeIngressFromAlb#{c.logical}:
+                  Type: AWS::EC2::SecurityGroupIngress
+                  Properties:
+                    GroupId: !Ref OwningSecurityGroupId
+                    IpProtocol: tcp
+                    FromPort: #{c.port}
+                    ToPort: #{c.port}
+                    SourceSecurityGroupId: !Ref AlbSecurityGroup
+              YAML
+            end
+            [alb_security_group(settings), "#{INGRESS_NOTE}\n#{ingress.join("\n\n")}"]
+          end
+
+          # Renders the load balancer's security group, open to CloudFront's prefix list only.
+          #
+          # @param settings [Settings] the resolved preview settings
+          # @return [String] the resource block
+          def alb_security_group(settings)
+            <<~YAML.chomp
+              AlbSecurityGroup:
+                Type: AWS::EC2::SecurityGroup
+                Properties:
+                  VpcId: !Ref OwningVpcId
+                  GroupDescription: !Sub "#{settings.infra_name} preview ${EnvName} ALB - HTTP ingress from CloudFront only"
+                  SecurityGroupIngress:
+                    # The AWS-managed com.amazonaws.global.cloudfront.origin-facing prefix list.
+                    - IpProtocol: tcp
+                      FromPort: 80
+                      ToPort: 80
+                      SourcePrefixListId: #{CLOUDFRONT_PREFIX_LIST}
+            YAML
+          end
+
+          # Renders the target groups, the load balancer, its listener and the path rules.
+          #
+          # @param settings [Settings] the resolved preview settings
+          # @return [Array<String>] the resource blocks
+          def load_balancing(settings)
+            routed = settings.containers.select(&:routed?)
+            [*routed.map { |c| target_group(c) }, alb(settings), listener(settings), *listener_rules(settings)]
+          end
+
+          # Renders the target group of one routed container.
+          #
+          # @param container [Containers::Entry] the container
+          # @return [String] the resource block
+          def target_group(container)
+            <<~YAML.chomp
+              #{container.logical}TargetGroup:
+                Type: AWS::ElasticLoadBalancingV2::TargetGroup
+                Properties:
+                  TargetType: ip
+                  Port: #{container.port}
+                  Protocol: HTTP
+                  VpcId: !Ref OwningVpcId
+                  HealthCheckPath: #{container.health_check_path}
+                  HealthCheckPort: "#{container.port}"
+            YAML
+          end
+
+          # Renders the internet-facing application load balancer.
+          #
+          # @param settings [Settings] the resolved preview settings
+          # @return [String] the resource block
+          def alb(settings)
+            <<~YAML.chomp
+              Alb:
+                Type: AWS::ElasticLoadBalancingV2::LoadBalancer
+                Properties:
+                  Name: !Sub "#{settings.alb_prefix}-${EnvName}"
+                  Scheme: internet-facing
+                  Type: application
+                  SecurityGroups: [!Ref AlbSecurityGroup]
+                  Subnets: [!Ref OwningPublicSubnetAId, !Ref OwningPublicSubnetBId]
+            YAML
+          end
+
+          # Renders the port 80 listener, whose default action goes to the default container.
+          #
+          # @param settings [Settings] the resolved preview settings
+          # @return [String] the resource block
+          def listener(settings)
+            <<~YAML.chomp
+              Listener:
+                Type: AWS::ElasticLoadBalancingV2::Listener
+                Properties:
+                  LoadBalancerArn: !Ref Alb
+                  Port: 80
+                  Protocol: HTTP
+                  DefaultActions:
+                    - Type: forward
+                      TargetGroupArn: !Ref #{settings.default_container.logical}TargetGroup
+            YAML
+          end
+
+          # Lists the listener rules to render: a non-default container's paths, sliced to
+          # fit one condition.
+          #
+          # @param settings [Settings] the resolved preview settings
+          # @return [Array<Hash{Symbol => Object}>] entries with `:container`, `:paths` and `:id`
+          def rule_specs(settings)
+            settings.containers.reject(&:default).select(&:routed?).flat_map do |c|
+              c.paths.each_slice(PATHS_PER_RULE).with_index.map do |slice, n|
+                { container: c, paths: slice, id: rule_id(c, n) }
+              end
+            end
+          end
+
+          # Renders every listener rule, with priorities counting up in tens.
+          #
+          # @param settings [Settings] the resolved preview settings
+          # @return [Array<String>] the resource blocks
+          def listener_rules(settings)
+            rule_specs(settings).each_with_index.map { |spec, i| listener_rule(spec, (i + 1) * 10) }
+          end
+
+          # Renders one listener rule.
+          #
+          # @param spec [Hash{Symbol => Object}] one entry of `rule_specs`
+          # @param priority [Integer] the rule's listener priority
+          # @return [String] the resource block
+          def listener_rule(spec, priority)
+            <<~YAML.chomp
+              #{spec[:id]}:
+                Type: AWS::ElasticLoadBalancingV2::ListenerRule
+                Properties:
+                  ListenerArn: !Ref Listener
+                  Priority: #{priority}
+                  Conditions:
+                    - Field: path-pattern
+                      Values: [#{spec[:paths].map { |p| JSON.generate(p) }.join(', ')}]
+                  Actions:
+                    - Type: forward
+                      TargetGroupArn: !Ref #{spec[:container].logical}TargetGroup
+            YAML
+          end
+
+          # Names one listener rule's logical id.
+          #
+          # @param container [Containers::Entry] the container the rule forwards to
+          # @param slice [Integer] the zero-based index of the rule among that container's rules
+          # @return [String] the logical id
+          def rule_id(container, slice) = "ListenerRule#{container.logical}#{slice + 1}"
+
+          # Renders the service, which registers every routed container with its target group.
+          #
+          # @param settings [Settings] the resolved preview settings
+          # @return [String] the resource block
+          def service(settings)
+            rule_ids = rule_specs(settings).map { |spec| spec[:id] }
+            <<~YAML.chomp
+              Service:
+                Type: AWS::ECS::Service
+                DependsOn: [#{(['Listener'] + rule_ids).join(', ')}]
+                Properties:
+                  ServiceName: !Sub "#{settings.prefix}-${EnvName}"
+                  Cluster: !Ref Cluster
+                  TaskDefinition: !Ref TaskDefinition
+                  DesiredCount: !Ref DesiredCount
+                  LaunchType: FARGATE
+                  EnableExecuteCommand: true
+                  NetworkConfiguration:
+                    AwsvpcConfiguration:
+                      AssignPublicIp: DISABLED
+                      Subnets: [!Ref OwningSubnetAId, !Ref OwningSubnetBId]
+                      SecurityGroups: [!Ref OwningSecurityGroupId]
+                  LoadBalancers:
+              #{indent(service_load_balancers(settings), 6)}
+            YAML
+          end
+
+          # Renders the service's load balancer registrations.
+          #
+          # @param settings [Settings] the resolved preview settings
+          # @return [String] one list entry per routed container
+          def service_load_balancers(settings)
+            settings.containers.select(&:routed?).map do |c|
+              "- ContainerName: #{c.name}\n  ContainerPort: #{c.port}\n  TargetGroupArn: !Ref #{c.logical}TargetGroup"
+            end.join("\n")
+          end
+        end
+      end
+    end
+  end
+end