Runtime Configuration

/bookshelf/prod/catalog-api/page-size            String
/bookshelf/prod/catalog-api/upstream-timeout     String
/bookshelf/prod/catalog-api/db/password          SecureString   (reference only; see the secrets page)
/bookshelf/prod/orders-api/retry-max-attempts    String
/bookshelf/dev/catalog-api/page-size             String

export AWS_REGION=us-east-1

aws ssm put-parameter \
  --name /bookshelf/prod/catalog-api/page-size \
  --type String --value 25 --tier Standard

# Every parameter of one service, one request (the call is paginated; recursive walks sub-paths)
aws ssm get-parameters-by-path \
  --path /bookshelf/prod/catalog-api/ --recursive \
  --query "Parameters[].{Name:Name,Value:Value,Version:Version}" --output table

# Update (a new version), then pin a label to the version you reviewed
aws ssm put-parameter --name /bookshelf/prod/catalog-api/page-size \
  --type String --value 50 --overwrite
aws ssm label-parameter-version \
  --name /bookshelf/prod/catalog-api/page-size --parameter-version 1 --labels approved

# Read by label or by version: name:label and name:version
aws ssm get-parameter --name /bookshelf/prod/catalog-api/page-size:approved \
  --query Parameter.Value --output text
aws ssm get-parameter-history --name /bookshelf/prod/catalog-api/page-size \
  --query "Parameters[].{Version:Version,Value:Value,Labels:Labels}"

aws ssm put-parameter \
  --name /bookshelf/prod/catalog-api/promo-banner \
  --type String --value "spring-sale" --tier Advanced \
  --policies '[{"Type":"NoChangeNotification","Version":"1.0","Attributes":{"After":"30","Unit":"Days"}}]'

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ReadCatalogApiParameters",
      "Effect": "Allow",
      "Action": ["ssm:GetParameter", "ssm:GetParameters", "ssm:GetParametersByPath"],
      "Resource": [
        "arn:aws:ssm:us-east-1:111122223333:parameter/bookshelf/prod/catalog-api",
        "arn:aws:ssm:us-east-1:111122223333:parameter/bookshelf/prod/catalog-api/*"
      ]
    }
  ]
}

{
  "Version": "2012-10-17",
  "Statement": [
    { "Effect": "Allow", "Action": "cloudwatch:DescribeAlarms", "Resource": "*" }
  ]
}

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": { "Service": "appconfig.amazonaws.com" },
      "Action": "sts:AssumeRole"
    }
  ]
}

aws iam create-role --role-name bookshelf-appconfig-monitor \
  --assume-role-policy-document file://appconfig-trust.json
aws iam put-role-policy --role-name bookshelf-appconfig-monitor --policy-name describe-alarms \
  --policy-document file://describe-alarms.json

aws cloudwatch put-metric-alarm --alarm-name bookshelf-catalog-api-5xx \
  --namespace AWS/ApplicationELB --metric-name HTTPCode_Target_5XX_Count \
  --dimensions Name=LoadBalancer,Value=app/alb-bookshelf/0123456789abcdef \
  --statistic Sum --period 60 --evaluation-periods 3 --threshold 20 \
  --comparison-operator GreaterThanThreshold --treat-missing-data notBreaching

export AWS_REGION=us-east-1
export ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)

APP_ID=$(aws appconfig create-application --name bookshelf \
  --query Id --output text)

ENV_ID=$(aws appconfig create-environment \
  --application-id "$APP_ID" --name prod \
  --monitors "[{\"AlarmArn\":\"arn:aws:cloudwatch:${AWS_REGION}:${ACCOUNT_ID}:alarm:bookshelf-catalog-api-5xx\",\"AlarmRoleArn\":\"arn:aws:iam::${ACCOUNT_ID}:role/bookshelf-appconfig-monitor\"}]" \
  --query Id --output text)

cat > catalog-settings.schema.json <<'EOF2'
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "pageSize":       { "type": "integer", "minimum": 1, "maximum": 100 },
    "upstreamTimeoutMs": { "type": "integer", "minimum": 100, "maximum": 30000 }
  },
  "required": ["pageSize", "upstreamTimeoutMs"],
  "additionalProperties": false
}
EOF2

PROFILE_ID=$(aws appconfig create-configuration-profile \
  --application-id "$APP_ID" --name catalog-settings \
  --location-uri hosted --type AWS.Freeform \
  --validators "[{\"Type\":\"JSON_SCHEMA\",\"Content\":$(jq -Rs . < catalog-settings.schema.json)}]" \
  --query Id --output text)

echo '{"pageSize": 25, "upstreamTimeoutMs": 2000}' > catalog-settings.json

aws appconfig create-hosted-configuration-version \
  --application-id "$APP_ID" --configuration-profile-id "$PROFILE_ID" \
  --content-type "application/json" \
  --content fileb://catalog-settings.json \
  --query VersionNumber catalog-settings.out

aws appconfig start-deployment \
  --application-id "$APP_ID" --environment-id "$ENV_ID" \
  --configuration-profile-id "$PROFILE_ID" --configuration-version 1 \
  --deployment-strategy-id AppConfig.Canary10Percent20Minutes \
  --description "page size 25"

aws appconfig list-deployments --application-id "$APP_ID" --environment-id "$ENV_ID" \
  --query "Items[].{N:DeploymentNumber,State:State,Percent:PercentageComplete}" --output table

STRATEGY_ID=$(aws appconfig create-deployment-strategy \
  --name bookshelf-canary-10-30 \
  --deployment-duration-in-minutes 30 --growth-factor 10 --growth-type EXPONENTIAL \
  --final-bake-time-in-minutes 15 --replicate-to NONE \
  --query Id --output text)

# Roll back an in-progress deployment (the callers return to the previous version)
aws appconfig stop-deployment \
  --application-id "$APP_ID" --environment-id "$ENV_ID" --deployment-number 2

FLAGS_ID=$(aws appconfig create-configuration-profile \
  --application-id "$APP_ID" --name catalog-flags \
  --location-uri hosted --type AWS.AppConfig.FeatureFlags \
  --query Id --output text)

cat > catalog-flags.json <<'EOF2'
{
  "version": "1",
  "flags": {
    "catalog-recommendations": {
      "name": "Catalog recommendations",
      "attributes": {
        "maxItems": { "constraints": { "type": "number", "required": true, "minimum": 1, "maximum": 50 } }
      }
    }
  },
  "values": {
    "catalog-recommendations": { "enabled": false, "maxItems": 10 }
  }
}
EOF2

aws appconfig create-hosted-configuration-version \
  --application-id "$APP_ID" --configuration-profile-id "$FLAGS_ID" \
  --content-type "application/json" --content fileb://catalog-flags.json \
  --query VersionNumber catalog-flags.out

TOKEN=$(aws appconfigdata start-configuration-session \
  --application-identifier bookshelf --environment-identifier prod \
  --configuration-profile-identifier catalog-settings \
  --required-minimum-poll-interval-in-seconds 60 \
  --query InitialConfigurationToken --output text)

# First call returns the content; the response carries the token for the next poll
aws appconfigdata get-latest-configuration --configuration-token "$TOKEN" settings.out

LAYER_ARN="<layer-arn-for-your-region-and-architecture-from-the-versions-page>"

aws lambda update-function-configuration --function-name notifier \
  --layers "$LAYER_ARN" \
  --environment "Variables={AWS_APPCONFIG_EXTENSION_PREFETCH_LIST=/applications/bookshelf/environments/prod/configurations/catalog-flags,AWS_APPCONFIG_EXTENSION_POLL_INTERVAL_SECONDS=60}"

{
  "name": "appconfig-agent",
  "image": "public.ecr.aws/aws-appconfig/aws-appconfig-agent:2.x",
  "essential": true,
  "portMappings": [ { "containerPort": 2772, "protocol": "tcp" } ],
  "environment": [
    { "name": "POLL_INTERVAL", "value": "60s" },
    { "name": "PREFETCH_LIST", "value": "bookshelf:prod:catalog-settings,bookshelf:prod:catalog-flags" },
    { "name": "SERVICE_REGION", "value": "us-east-1" }
  ],
  "logConfiguration": {
    "logDriver": "awslogs",
    "options": {
      "awslogs-group": "/ecs/bookshelf",
      "awslogs-region": "us-east-1",
      "awslogs-stream-prefix": "appconfig-agent"
    }
  }
}

spec:
  serviceAccountName: orders-api
  containers:
    - name: orders-api
      image: 111122223333.dkr.ecr.us-east-1.amazonaws.com/bookshelf/orders-api:1.0.0
      env:
        - name: APPCONFIG_URL
          value: http://localhost:2772/applications/bookshelf/environments/prod/configurations
    - name: appconfig-agent
      image: public.ecr.aws/aws-appconfig/aws-appconfig-agent:2.x
      ports:
        - name: http
          containerPort: 2772
          protocol: TCP
      env:
        - name: SERVICE_REGION
          value: us-east-1
        - name: POLL_INTERVAL
          value: 60s
      imagePullPolicy: IfNotPresent

package com.example.bookshelf.config;

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class FlagClient {

    private final HttpClient http = HttpClient.newBuilder()
            .connectTimeout(Duration.ofMillis(200)).build();
    private final ObjectMapper mapper = new ObjectMapper();
    private final String baseUrl; // http://localhost:2772/applications/bookshelf/environments/prod/configurations

    public FlagClient(String baseUrl) {
        this.baseUrl = baseUrl;
    }

    /** Returns the flag's enabled state, or {@code fallback} if the agent cannot answer. */
    public boolean isEnabled(String profile, String flag, String entityId, boolean fallback) {
        try {
            HttpRequest.Builder request = HttpRequest.newBuilder()
                    .uri(URI.create(baseUrl + "/" + profile + "?flag=" + flag))
                    .timeout(Duration.ofMillis(500));
            if (entityId != null) {
                request.header("Entity-Id", entityId); // sticky rollout per customer
            }
            HttpResponse<String> response =
                    http.send(request.build(), HttpResponse.BodyHandlers.ofString());
            if (response.statusCode() != 200) {
                return fallback;
            }
            JsonNode body = mapper.readTree(response.body());
            return body.path("enabled").asBoolean(fallback);
        } catch (Exception e) {
            return fallback;
        }
    }
}