hecks 2.6.0 → 2.8.0

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

@@ -0,0 +1,40 @@
+require "erb"
+
+module Hecks
+  module Projections
+    module Deploy
+      module Preview
+        # Renders `preview.sh`, the script that creates, updates and deletes one
+        # branch's preview stack.
+        #
+        # The script text lives in `preview.sh.erb` beside this file because it
+        # is a shell program, not Ruby: keeping it as a file lets `bash -n` and
+        # `shellcheck` read it as one. Every value baked into it has already
+        # passed `Settings`' patterns, so the template never quotes defensively.
+        module Script
+          TEMPLATE = File.join(__dir__, "preview.sh.erb").freeze
+
+          module_function
+
+          # Renders the script.
+          #
+          # @param settings [Settings] the resolved preview settings
+          # @return [String] the bash script, ending in one newline
+          def render(settings)
+            ERB.new(File.read(TEMPLATE), trim_mode: "-").result_with_hash(
+              s: settings, image_hint: image_hint(settings)
+            )
+          end
+
+          # Names the local images `deploy` expects, for the script's header.
+          #
+          # @param settings [Settings] the resolved preview settings
+          # @return [String] the image references, comma separated
+          def image_hint(settings)
+            settings.containers.map(&:image).join(", ")
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,140 @@
+require_relative "containers"
+
+module Hecks
+  module Projections
+    module Deploy
+      module Preview
+        # The resolved, validated settings of one preview stack family.
+        #
+        # `Settings.build` is the only place a raw `preview` block meets the
+        # main stack's own facts, so every default lives here and the two
+        # renderers (`Template`, `Script`) read plain values.
+        #
+        # ## Why validation is this strict
+        #
+        # Every value ends up in a CloudFormation name, a Postgres database
+        # name that `CREATE DATABASE` cannot parameterize, or a shell script
+        # baked with the value. Patterns are checked once here, so neither
+        # renderer has to quote defensively.
+        class Settings
+          KEYS = %i[prefix alb_prefix owner_stack database_stack database_endpoint_output database_secret_output
+                    db_prefix protected_databases protected_branches cpu memory log_retention_days session_cookie
+                    first_admin signup_path landing_path db_init_image containers].freeze
+
+          DEFAULT_DB_INIT_IMAGE = "public.ecr.aws/docker/library/postgres:16-alpine".freeze
+          PREFIX_PATTERN = /\A[a-z0-9][a-z0-9-]{0,59}\z/
+          ALB_PREFIX_PATTERN = /\A[a-z0-9][a-z0-9-]{0,9}[a-z0-9]\z/
+          DB_PREFIX_PATTERN = /\A[a-z][a-z0-9_]{0,29}\z/
+          STACK_PATTERN = /\A[A-Za-z][A-Za-z0-9_-]{0,127}\z/
+          OUTPUT_PATTERN = /\A[A-Za-z0-9]+\z/
+          BRANCH_PATTERN = %r{\A[A-Za-z0-9._/-]+\z}
+          PATH_PATTERN = Containers::PATH_PATTERN
+          COOKIE_PATTERN = /\A[A-Za-z0-9_.-]+\z/
+          RETENTION_DAYS = [1, 3, 5, 7, 14, 30, 60, 90].freeze
+
+          attr_reader(*KEYS, :region, :stack_name, :infra_name, :main)
+
+          # Builds the settings for one domain's previews.
+          #
+          # @param raw [Hash{Symbol => Object}, true] the `preview` block; `true` accepts
+          #   every default
+          # @param deploy_settings [Hash{Symbol => Object}] the `deployed_to` settings
+          # @param main [Hash{Symbol => Object}] the main stack's facts: `:infra_name`,
+          #   `:stack_name`,
+          #   `:stack_prefix`, `:region`, `:cpu`, `:memory`, `:db_name`, `:owner_stack` (nil unless
+          #   the main stack borrows a database), `:name`, `:port`, `:image`, `:domain`, `:web`,
+          #   `:wasm_path`, `:ir_path`, `:schema`
+          # @return [Settings] the validated settings
+          # @raise [ArgumentError] if a key is unknown or a value breaks its pattern
+          def self.build(raw, deploy_settings:, main:)
+            raw = raw.is_a?(Hash) ? raw.transform_keys(&:to_sym) : {}
+            unknown = raw.keys - KEYS
+            unless unknown.empty?
+              raise ArgumentError, "unknown preview setting(s): #{unknown.join(', ')} (known: #{KEYS.join(', ')})"
+            end
+
+            new(raw, deploy_settings, main)
+          end
+
+          # @param raw [Hash{Symbol => Object}] the symbolized `preview` settings
+          # @param deploy_settings [Hash{Symbol => Object}] the `deployed_to` settings
+          # @param main [Hash{Symbol => Object}] the main stack's facts, see `build`
+          def initialize(raw, deploy_settings, main)
+            @main = main
+            @region = main.fetch(:region)
+            @stack_name = main.fetch(:stack_name)
+            @infra_name = main.fetch(:infra_name)
+            assign_names(raw, main)
+            assign_database(raw, main)
+            assign_sizing(raw, main)
+            assign_behaviour(raw)
+            @containers = Containers.resolve(preview: raw, deploy_settings: deploy_settings, main: main,
+                                             signup_path: (signup_path if first_admin))
+          end
+
+          # Answers the host container, when the task has one.
+          #
+          # @return [Containers::Entry, nil] the entry flagged `host`
+          def host = containers.find(&:host)
+
+          # Answers the container that receives unmatched requests.
+          #
+          # @return [Containers::Entry] the default entry
+          def default_container = containers.find(&:default)
+
+          private
+
+          def assign_names(raw, main)
+            prefix_default = "#{main.fetch(:stack_prefix)}-#{infra_name}-preview".downcase.gsub(/[^a-z0-9-]+/, "-")
+            @prefix = pick(raw, :prefix, prefix_default, PREFIX_PATTERN)
+            alb_default = "#{infra_name.downcase.gsub(/[^a-z0-9]/, '')[0, 8]}pv"
+            @alb_prefix = pick(raw, :alb_prefix, alb_default, ALB_PREFIX_PATTERN)
+            @owner_stack = pick(raw, :owner_stack, main[:owner_stack] || stack_name, STACK_PATTERN)
+            @database_stack = pick(raw, :database_stack, owner_stack, STACK_PATTERN)
+            @database_endpoint_output = pick(raw, :database_endpoint_output, "DatabaseEndpoint", OUTPUT_PATTERN)
+            @database_secret_output = pick(raw, :database_secret_output, "DatabaseSecretArn", OUTPUT_PATTERN)
+          end
+
+          def assign_database(raw, main)
+            db_default = infra_name.downcase.gsub(/[^a-z0-9]+/, "_").sub(/\A[^a-z]+/, "")[0, 30].sub(/_+\z/, "")
+            @db_prefix = pick(raw, :db_prefix, db_default, DB_PREFIX_PATTERN)
+            extra = Array(raw[:protected_databases]).map(&:to_s)
+            @protected_databases = ([main.fetch(:db_name).to_s.downcase, "postgres", "template0", "template1"] + extra).uniq
+          end
+
+          def assign_sizing(raw, main)
+            @cpu = Integer(raw.fetch(:cpu, main.fetch(:cpu)))
+            @memory = Integer(raw.fetch(:memory, main.fetch(:memory)))
+            @log_retention_days = Integer(raw.fetch(:log_retention_days, 7))
+            return if RETENTION_DAYS.include?(log_retention_days)
+
+            raise ArgumentError, "preview log_retention_days must be one of #{RETENTION_DAYS.join(', ')}"
+          end
+
+          def assign_behaviour(raw)
+            @protected_branches = Array(raw.fetch(:protected_branches, %w[main master])).map(&:to_s)
+            unless protected_branches.all? { |b| b.match?(BRANCH_PATTERN) }
+              raise ArgumentError, "preview protected_branches must be plain branch names"
+            end
+
+            @session_cookie = pick(raw, :session_cookie, nil, COOKIE_PATTERN)
+            @first_admin = raw.fetch(:first_admin, true) != false
+            @signup_path = pick(raw, :signup_path, "/signups", PATH_PATTERN)
+            @landing_path = pick(raw, :landing_path, "/", PATH_PATTERN)
+            @db_init_image = pick(raw, :db_init_image, DEFAULT_DB_INIT_IMAGE, %r{\A[A-Za-z0-9./:_@-]+\z})
+          end
+
+          def pick(raw, key, default, pattern)
+            value = raw.key?(key) ? raw[key] : default
+            return value if value.nil?
+
+            value = value.to_s
+            return value if value.match?(pattern)
+
+            raise ArgumentError, "preview #{key} #{value.inspect} must match #{pattern.inspect}"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,215 @@
+require "json"
+require_relative "yaml_text"
+
+module Hecks
+  module Projections
+    module Deploy
+      module Preview
+        # The task definitions of a preview stack: the containers it runs and the
+        # one-shot task that creates its database.
+        #
+        # The host container gets the domain, session and database environment; a
+        # container's own `environment` wins over a generated entry of the same name.
+        module TaskYaml
+          # The one-shot task's script. Idempotent, and refuses names the preview must never touch.
+          DB_INIT_SCRIPT = <<~SH.freeze
+            set -eu
+            case "$TARGET_DB" in
+              ""|*[!a-z0-9_]*) echo "refusing TARGET_DB '$TARGET_DB': lowercase letters, digits and underscores only" >&2; exit 1 ;;
+            esac
+            [ "${#TARGET_DB}" -le 63 ] || { echo "refusing TARGET_DB '$TARGET_DB': longer than 63 characters" >&2; exit 1; }
+            for protected in $PROTECTED_DATABASES; do
+              [ "$TARGET_DB" != "$protected" ] || { echo "refusing to manage the protected database '$protected'" >&2; exit 1; }
+            done
+            export PGSSLMODE=require PGCONNECT_TIMEOUT=10
+            found=$(psql -h "$DB_HOST" -U "$PGUSER" -d postgres -Atc "SELECT 1 FROM pg_database WHERE datname = '$TARGET_DB'")
+            if [ "${ACTION:-create}" = "drop" ]; then
+              if [ "$found" = "1" ]; then
+                psql -v ON_ERROR_STOP=1 -h "$DB_HOST" -U "$PGUSER" -d postgres -c "DROP DATABASE \\"$TARGET_DB\\" WITH (FORCE)"
+                echo "dropped database $TARGET_DB"
+              else
+                echo "database $TARGET_DB does not exist"
+              fi
+            elif [ "$found" = "1" ]; then
+              echo "database $TARGET_DB already exists"
+            else
+              psql -v ON_ERROR_STOP=1 -h "$DB_HOST" -U "$PGUSER" -d postgres -c "CREATE DATABASE \\"$TARGET_DB\\""
+              echo "created database $TARGET_DB"
+            fi
+          SH
+
+          # The database credentials as container secrets, so the password never appears as a plain
+          # value in the task definition.
+          DB_INIT_SECRETS = <<~YAML.chomp.freeze
+            Secrets:
+              - Name: PGUSER
+                ValueFrom: !Sub "${OwningDatabaseSecretArn}:username::"
+              - Name: PGPASSWORD
+                ValueFrom: !Sub "${OwningDatabaseSecretArn}:password::"
+          YAML
+
+          extend YamlText
+
+          module_function
+
+          # Renders the one-shot task that creates (or drops) this preview's database.
+          #
+          # @param settings [Settings] the resolved preview settings
+          # @return [String] the task definition's resource block
+          def db_init_task(settings)
+            <<~YAML.chomp
+              # Run by preview.sh (`aws ecs run-task`) after the images are pushed and before the
+              # service scales up: the database instance is reachable only from inside the VPC, so
+              # this is the one place a laptop-driven deploy can run CREATE DATABASE. Idempotent.
+              DbInitTaskDefinition:
+                Type: AWS::ECS::TaskDefinition
+                Properties:
+                  Family: !Sub "#{settings.prefix}-${EnvName}-dbinit"
+                  RequiresCompatibilities: [FARGATE]
+                  NetworkMode: awsvpc
+                  Cpu: "256"
+                  Memory: "512"
+                  RuntimePlatform:
+                    CpuArchitecture: ARM64
+                    OperatingSystemFamily: LINUX
+                  ExecutionRoleArn: !GetAtt ExecutionRole.Arn
+                  TaskRoleArn: !GetAtt TaskRole.Arn
+                  ContainerDefinitions:
+                    - Name: dbinit
+                      Image: #{settings.db_init_image}
+                      Essential: true
+                      Command:
+                        - sh
+                        - -c
+                        - |
+              #{indent(DB_INIT_SCRIPT.chomp, 12)}
+                      LogConfiguration:
+                        LogDriver: awslogs
+                        Options:
+                          awslogs-group: !Ref LogGroup
+                          awslogs-region: !Ref AWS::Region
+                          awslogs-stream-prefix: dbinit
+                      Environment:
+                        - Name: DB_HOST
+                          Value: !Ref OwningDatabaseEndpoint
+                        - Name: TARGET_DB
+                          Value: !Ref DbName
+                        - Name: PROTECTED_DATABASES
+                          Value: #{JSON.generate(settings.protected_databases.join(' '))}
+              #{indent(DB_INIT_SECRETS, 8)}
+            YAML
+          end
+
+          # Renders the preview's task definition, one container per entry of the container list.
+          #
+          # @param settings [Settings] the resolved preview settings
+          # @return [String] the task definition's resource block
+          def task_definition(settings)
+            <<~YAML.chomp
+              TaskDefinition:
+                Type: AWS::ECS::TaskDefinition
+                Properties:
+                  Family: !Sub "#{settings.prefix}-${EnvName}"
+                  RequiresCompatibilities: [FARGATE]
+                  NetworkMode: awsvpc
+                  Cpu: "#{settings.cpu}"
+                  Memory: "#{settings.memory}"
+                  RuntimePlatform:
+                    CpuArchitecture: ARM64
+                    OperatingSystemFamily: LINUX
+                  ExecutionRoleArn: !GetAtt ExecutionRole.Arn
+                  TaskRoleArn: !GetAtt TaskRole.Arn
+                  ContainerDefinitions:
+              #{indent(settings.containers.map { |c| container_definition(settings, c) }.join("\n"), 6)}
+            YAML
+          end
+
+          # Renders one container of the task definition.
+          #
+          # @param settings [Settings] the resolved preview settings
+          # @param container [Containers::Entry] the container
+          # @return [String] the list entry
+          def container_definition(settings, container)
+            lines = [
+              "- Name: #{container.name}",
+              %(  Image: !Sub "${#{container.logical}Repository.RepositoryUri}:${#{container.logical}ImageTag}"),
+              "  Essential: true"
+            ]
+            lines += ["  PortMappings:", "    - ContainerPort: #{container.port}"] if container.routed?
+            lines += ["  LogConfiguration:", indent(log_options(container), 4).chomp]
+            lines += ["  Environment:", indent(environment_yaml(settings, container), 4).chomp]
+            lines.join("\n")
+          end
+
+          # Renders the log driver settings of one container.
+          #
+          # @param container [Containers::Entry] the container
+          # @return [String] the settings, ending in a newline
+          def log_options(container)
+            <<~YAML
+              LogDriver: awslogs
+              Options:
+                awslogs-group: !Ref LogGroup
+                awslogs-region: !Ref AWS::Region
+                awslogs-stream-prefix: #{container.name}
+            YAML
+          end
+
+          # Renders one container's environment as a list.
+          #
+          # @param settings [Settings] the resolved preview settings
+          # @param container [Containers::Entry] the container
+          # @return [String] the list entries
+          def environment_yaml(settings, container)
+            environment_pairs(settings, container).map do |name, value|
+              "- Name: #{name}\n  Value: #{value}"
+            end.join("\n")
+          end
+
+          # Orders one container's environment as `[name, rendered value]` pairs; the container's
+          # `environment` wins over a generated entry of the same name.
+          #
+          # @param settings [Settings] the resolved preview settings
+          # @param container [Containers::Entry] the container
+          # @return [Array<Array(String, String)>] the pairs, each value already rendered as YAML
+          def environment_pairs(settings, container)
+            pairs = { "PORT" => scalar(container.port.to_s) }
+            pairs.merge!(host_environment(settings)) if container.host
+            pairs.merge!(database_environment) if container.host || container.database
+            container.secrets.each { |name| pairs[name] = "!Ref #{secret_id(container, name)}" }
+            container.environment.each { |name, value| pairs[name] = scalar(value) }
+            pairs.to_a
+          end
+
+          # Answers the environment only the Hecks host container gets.
+          #
+          # @param settings [Settings] the resolved preview settings
+          # @return [Hash{String => String}] name to rendered value
+          def host_environment(settings)
+            main = settings.main
+            pairs = {
+              "HECKS_DOMAIN" => scalar(main.fetch(:domain)), "HECKS_ERA" => scalar("1"),
+              "PORT" => scalar(settings.host.port.to_s), "BIND" => scalar("0.0.0.0"),
+              "HECKS_SERVE_MODE" => scalar("1"), "HECKS_WEB" => scalar(main.fetch(:web)),
+              "HECKS_WASM_PATH" => scalar(main.fetch(:wasm_path)), "HECKS_IR_PATH" => scalar(main.fetch(:ir_path)),
+              "SESSION_SECRET_ARN" => "!Ref SessionSecret", "HECKS_CHECKOUT_DOMAIN" => scalar(main.fetch(:domain))
+            }
+            pairs["HECKS_SCHEMA"] = scalar(main[:schema]) if main[:schema]
+            pairs["HECKS_SESSION_COOKIE"] = scalar(settings.session_cookie) if settings.session_cookie
+            pairs
+          end
+
+          # Answers the environment that points a container at this preview's database.
+          #
+          # @return [Hash{String => String}] name to rendered value
+          def database_environment
+            {
+              "DB_HOST" => "!Ref OwningDatabaseEndpoint", "DB_NAME" => "!Ref DbName",
+              "DB_SECRET_ARN" => "!Ref OwningDatabaseSecretArn"
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,247 @@
+require "json"
+require_relative "yaml_text"
+require_relative "access_yaml"
+require_relative "task_yaml"
+require_relative "routing_yaml"
+
+module Hecks
+  module Projections
+    module Deploy
+      module Preview
+        # Renders `preview.yaml`, the CloudFormation template of one
+        # per-branch preview stack.
+        #
+        # A separate template rather than conditions threaded through the main
+        # one, so a preview can never put the main stack's live resources in a
+        # change set. The two share a task shape and nothing else.
+        #
+        # ## What a preview owns
+        #
+        # Per branch: a cluster, service and task, a load balancer, one image
+        # repository per container, a session secret, any secrets a container
+        # declares, a log group, a CloudFront distribution (default hostname,
+        # nothing cached) and a database name on the shared instance, created
+        # by a one-shot task before the service starts.
+        #
+        # ## What it borrows and leaves out
+        #
+        # It attaches to the owner stack's VPC, subnets and compute security
+        # group and connects to the shared database instance, through the same
+        # `Owning*` parameters the main template takes for `database "Shared"`.
+        # It has no alarms, no notifications, no warmer and no custom domain:
+        # nobody should be paged for a preview.
+        module Template
+          CACHING_DISABLED = "4135ea2d-6df8-44a3-9df3-4b5a84be39ad".freeze
+          ALL_VIEWER = "216adef6-5c7f-47e4-b989-5492eafa07d3".freeze
+
+          extend YamlText
+
+          module_function
+
+          # Renders the whole template.
+          #
+          # @param settings [Settings] the resolved preview settings
+          # @return [String] the CloudFormation YAML, ending in one newline
+          def render(settings)
+            [
+              header(settings), parameters(settings),
+              "Resources:\n#{indent(resources(settings).join("\n\n"), 2)}",
+              outputs
+            ].join("\n") << "\n"
+          end
+
+          # Renders the file's leading comment and template description.
+          #
+          # @param settings [Settings] the resolved preview settings
+          # @return [String] the header block
+          def header(settings)
+            <<~YAML.chomp
+              # 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").
+              #
+              # One stack per git branch, driven by preview.sh. A separate template from the main
+              # one on purpose, so a preview can never appear in a change set against the live
+              # stack. It shares the task shape and nothing else.
+              #
+              # Per branch: ECS cluster, service and task, an ALB, one ECR repository per
+              # container, secrets, a log group, a CloudFront distribution (default hostname,
+              # nothing cached) and its own database on the shared instance.
+              # Borrowed from #{settings.owner_stack}: VPC, subnets and the compute security group.
+              # Left out on purpose: alarms, notifications, warmers and custom domains.
+              AWSTemplateFormatVersion: '2010-09-09'
+              Description: >
+                #{settings.infra_name} preview - one feature branch, behind its own ALB and
+                CloudFront, on its own database.
+            YAML
+          end
+
+          # Renders the parameters section.
+          #
+          # @param settings [Settings] the resolved preview settings
+          # @return [String] the section, one image-tag parameter per container
+          def parameters(settings)
+            image_tags = settings.containers.map do |c|
+              <<~YAML.chomp
+                #{c.logical}ImageTag:
+                  Type: String
+                  Default: bootstrap
+              YAML
+            end
+            "Parameters:\n#{indent([base_parameters, *image_tags, desired_count_parameter].join("\n"), 2)}"
+          end
+
+          # Renders the parameters every preview takes: its name, database and the borrowed network.
+          #
+          # @return [String] the parameter blocks
+          def base_parameters
+            <<~YAML.chomp
+              EnvName:
+                Type: String
+                AllowedPattern: '^[a-z0-9]([a-z0-9-]{0,18}[a-z0-9])?$'
+                ConstraintDescription: lowercase letters, digits and hyphens, at most 20 characters, not ending in a hyphen (the ALB name limit is 32).
+              DbName:
+                Type: String
+                AllowedPattern: '^[a-z][a-z0-9_]{0,62}$'
+                Description: This preview's own database on the shared instance, created by the one-shot DbInit task before the service starts.
+              OwningVpcId:
+                Type: AWS::EC2::VPC::Id
+              OwningSubnetAId:
+                Type: AWS::EC2::Subnet::Id
+              OwningSubnetBId:
+                Type: AWS::EC2::Subnet::Id
+              OwningPublicSubnetAId:
+                Type: AWS::EC2::Subnet::Id
+              OwningPublicSubnetBId:
+                Type: AWS::EC2::Subnet::Id
+              OwningSecurityGroupId:
+                Type: AWS::EC2::SecurityGroup::Id
+              OwningDatabaseEndpoint:
+                Type: String
+              OwningDatabaseSecretArn:
+                Type: String
+            YAML
+          end
+
+          # Renders the parameter `preview.sh` uses to start the stack at zero tasks.
+          #
+          # @return [String] the parameter block
+          def desired_count_parameter
+            <<~YAML.chomp
+              # The repositories are created by this stack, so the first create has no image to
+              # point at. preview.sh creates the stack at 0, pushes, then scales up.
+              DesiredCount:
+                Type: Number
+                Default: 0
+            YAML
+          end
+
+          # Collects every resource block of the template.
+          #
+          # @param settings [Settings] the resolved preview settings
+          # @return [Array<String>] the resource blocks, in template order
+          def resources(settings)
+            [
+              AccessYaml.secrets(settings), RoutingYaml.networking(settings), repositories(settings),
+              cluster_and_logs(settings),
+              AccessYaml.roles(settings), TaskYaml.db_init_task(settings), TaskYaml.task_definition(settings),
+              RoutingYaml.load_balancing(settings),
+              RoutingYaml.service(settings), distribution
+            ].flatten
+          end
+
+          # Renders one image repository per container, emptied when the stack is deleted.
+          #
+          # @param settings [Settings] the resolved preview settings
+          # @return [Array<String>] the resource blocks
+          def repositories(settings)
+            settings.containers.map do |c|
+              <<~YAML.chomp
+                #{c.logical}Repository:
+                  Type: AWS::ECR::Repository
+                  Properties:
+                    RepositoryName: !Sub "#{settings.prefix}-${EnvName}-#{c.name}"
+                    EmptyOnDelete: true
+              YAML
+            end
+          end
+
+          # Renders the cluster and the log group.
+          #
+          # @param settings [Settings] the resolved preview settings
+          # @return [Array<String>] the two resource blocks
+          def cluster_and_logs(settings)
+            [
+              <<~YAML.chomp,
+                Cluster:
+                  Type: AWS::ECS::Cluster
+                  Properties:
+                    ClusterName: !Sub "#{settings.prefix}-${EnvName}"
+              YAML
+              <<~YAML.chomp
+                LogGroup:
+                  Type: AWS::Logs::LogGroup
+                  Properties:
+                    LogGroupName: !Sub "/ecs/#{settings.prefix}-${EnvName}"
+                    RetentionInDays: #{settings.log_retention_days}
+              YAML
+            ]
+          end
+
+          # Renders the CDN distribution, which caches nothing.
+          #
+          # @return [String] the resource block
+          def distribution
+            <<~YAML.chomp
+              # One behavior, nothing cached: a preview is for looking at a change, so no cache means
+              # no stale page after a redeploy and no session response served to the wrong visitor.
+              # AllViewer forwards the viewer's Host so a same-origin check sees the real hostname.
+              PreviewDistribution:
+                Type: AWS::CloudFront::Distribution
+                Properties:
+                  DistributionConfig:
+                    Enabled: true
+                    HttpVersion: http2
+                    Comment: !Sub "preview ${EnvName}"
+                    Origins:
+                      - Id: PreviewAlbOrigin
+                        DomainName: !GetAtt Alb.DNSName
+                        CustomOriginConfig:
+                          OriginProtocolPolicy: http-only
+                          OriginSSLProtocols: [TLSv1.2]
+                    DefaultCacheBehavior:
+                      TargetOriginId: PreviewAlbOrigin
+                      ViewerProtocolPolicy: redirect-to-https
+                      AllowedMethods: [GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE]
+                      CachedMethods: [GET, HEAD]
+                      Compress: true
+                      CachePolicyId: #{CACHING_DISABLED}
+                      OriginRequestPolicyId: #{ALL_VIEWER}
+            YAML
+          end
+
+          # Renders the outputs `preview.sh` reads back.
+          #
+          # @return [String] the section
+          def outputs
+            <<~YAML.chomp
+              Outputs:
+                PreviewUrl:
+                  Value: !Sub "https://${PreviewDistribution.DomainName}"
+                ClusterName:
+                  Value: !Ref Cluster
+                ServiceName:
+                  Value: !GetAtt Service.Name
+                DbInitTaskDefinition:
+                  Value: !Ref DbInitTaskDefinition
+                # The ARN only, so preview.sh can fetch the secret to mint signup and session tokens.
+                SessionSecretArn:
+                  Value: !Ref SessionSecret
+                DatabaseName:
+                  Value: !Ref DbName
+            YAML
+          end
+        end
+      end
+    end
+  end
+end