aws-appconfig

AWS AppConfig Plugin

Critical: Region Awareness

AppConfig is a regional service. Resources created in one region do not exist in another. Before running any aws appconfig CLI command:

1. Determine the target region — check the user's AWS_REGION, AWS_DEFAULT_REGION, or ask which region their AppConfig resources are in
2. Always pass --region to every aws appconfig and aws appconfigdata command, or verify the environment variable is set correctly
3. When working with existing resources, run aws appconfig list-applications --region <region> first to confirm the region is correct before proceeding with other commands
4. SAM templates deploy to a specific region (set in samconfig.toml). Subsequent CLI commands must target the same region — a mismatch is the most common cause of ResourceNotFoundException
5. Lambda layer ARNs are region-specific — the account ID in the ARN varies by region. Never hardcode a layer ARN from one region and deploy to another

Overview

Manage application configuration and feature flags with AWS AppConfig — a capability of AWS Systems Manager. This skill provides comprehensive guidance for dynamic configuration management, feature flag workflows, safe deployment strategies with automatic rollback, and integration with AWS Lambda, ECS, EKS, EC2, AWS Batch, and on-premises environments.

AWS AppConfig enables you to create, manage, and deploy application configurations and feature flags independently from code deployments. Configuration changes are deployed using strategies that validate changes and roll back automatically if a CloudWatch alarm fires.

Key capabilities:

• Feature Flags: Boolean, string, and number flags with multi-variant support, targeting rules, percentage rollouts (split operator), and time-based scheduling
• Freeform Configuration: JSON, YAML, or plain-text configuration profiles with JSON Schema and Lambda function validators
• Deployment Strategies: Linear, exponential (canary), and all-at-once deployments with automatic rollback on CloudWatch alarms
• Validation: JSON Schema validators (draft-04) and Lambda function validators (15-second timeout) to catch errors before deployment
• Lambda Integration: AppConfig Lambda extension layer for low-latency cached configuration retrieval via localhost:2772
• Container Integration: AppConfig Agent sidecar for ECS, EKS, and AWS Batch (public.ecr.aws/aws-appconfig/aws-appconfig-agent:2.x)
• EC2 / On-Premises: AppConfig Agent as a systemd daemon (RPM) or Docker container for EC2, on-premises, and hybrid environments
• Powertools Integration: Feature Flags rule engine (Python only) and Parameters utility (Python, TypeScript, Java, .NET)
• Extensions Framework: PRE/ON/AT action points for custom logic — Lambda, EventBridge, SNS, SQS integrations

Workflow Guidance

Refer to these supporting files for detailed guidance on specific workflows:

File	When to Use
getting-started.md	Decision tree, circuit breaker pattern, IaC options (SAM/CDK/Terraform/CloudFormation)
configuration-profiles.md	Application setup, environments, freeform configuration profiles, validators, configuration sources, CI/CD deployment patterns
feature-flags.md	Feature flag creation, native AppConfig feature flags, multi-variant flags, targeting rules, Powertools integration, testing patterns
deployment-strategies.md	Built-in and custom strategies, growth types, bake time, automatic rollback, revert, scheduled deployments
integration.md	Lambda extension, ECS/EKS agent, EC2 agent, AWS Batch, on-premises/hybrid, VPC endpoints, Lambda@Edge, Step Functions, Powertools Parameters, SDK polling, caching, multi-region, multi-account governance, browser/mobile proxy, local development
monitoring.md	CloudWatch metrics, deployment alarms, rollback notification pattern, extensions for EventBridge/SNS/SQS, CloudTrail auditing
troubleshooting.md	Symptom-based diagnosis and resolution for common AppConfig issues

Best Practices

Configuration Management

• Do: Use feature flags for runtime toggles instead of environment variables that require redeployment
• Do: Use freeform configuration profiles for structured settings (connection strings, timeouts, rate limits, allow/block lists)
• Do: Use the AWS AppConfig hosted configuration store — it has the most features and enhancements compared to S3 or SSM backends
• Do: Validate all configurations with JSON Schema validators (draft-04) before deployment. Important: validators do NOT run on create-hosted-configuration-version — invalid content is silently accepted. Always call aws appconfig validate-configuration explicitly before start-deployment
• Do: Use separate environments for dev, staging, and production with different deployment strategies
• Do: Use the AppConfig Agent (Lambda extension, container sidecar, or EC2 daemon) for retrieval — it implements best practices automatically
• Don't: Store secrets in AppConfig — use Secrets Manager or SSM SecureString parameters
• Don't: Use AllAtOnce deployment strategy in production without a CloudWatch alarm for rollback
• Don't: Use GetConfiguration API — it was deprecated January 28, 2022; use StartConfigurationSession + GetLatestConfiguration

Deployment Safety

• Do: Use AppConfig.Linear20PercentEvery6Minutes or AppConfig.Canary10Percent20Minutes for production deployments
• Do: Attach CloudWatch alarms to environments for automatic rollback during deployment and bake time
• Do: Set bake time >= your alarm evaluation period so alarms have time to detect issues
• Do: Test configuration changes in a non-production environment first
• Don't: Skip validators — they are your first line of defense against bad configuration
• Don't: Deploy configuration changes during peak traffic without a rollback alarm
• Don't: Disable CloudWatch alarm actions — disabled alarm actions prevent automatic rollback

Security

• Do: Follow least-privilege IAM — scope appconfig:GetLatestConfiguration to specific application/environment/profile ARNs
• Do: Use AWS KMS customer managed keys (CMK) for encrypting configuration data at rest (set KmsKeyIdentifier)
• Do: Enable CloudTrail logging for all AppConfig API calls for auditing
• Do: Use VPC interface endpoints (com.amazonaws.region.appconfig and com.amazonaws.region.appconfigdata) for private access
• Do: Use FIPS endpoints for FedRAMP/regulated workloads (appconfig-fips.region.amazonaws.com and appconfigdata-fips.region.amazonaws.com) — available in US and GovCloud regions
• Do: Use dual-stack (IPv6) endpoints when required (appconfig.region.api.aws and appconfigdata.region.api.aws) — available in all regions including GovCloud
• Don't: Grant appconfig:* — scope to specific actions and resource ARNs
• Don't: Store credentials, API keys, or secrets in AppConfig configuration profiles

AppConfig Limits Quick Reference

Resource	Default	Adjustable To	Notes
Applications per account per Region	100	300	Rarely hit
Configuration profiles per application	100	500	Rarely hit
Environments per application	20	100	Commonly hit in multi-stage pipelines — request increase early
Deployment strategies per account per Region	20	100	Rarely hit
Configuration size (hosted store)	2,048 KB (≈2 MB)	4,000 KB (≈4 MB)	Commonly hit with large flag sets — see configuration-profiles.md for split strategies
Deployment size	2,048 KB (≈2 MB)	4,000 KB (≈4 MB)	Same as above
Monitors (alarms) per environment	5 (hard limit)	—	Use composite alarms to combine signals within the 5-monitor limit
Validators per configuration profile	2 (hard limit)	—	One JSON Schema + one Lambda is the typical max
Feature flag attributes per flag	25 (hard limit)	—
Feature flag key length	64 characters (hard limit)	—
Feature flag variants per flag	32 (hard limit)	—
Active deployments per environment	1 (hard limit)	—	Common blocker — ConflictException if a deployment is in progress
Deployment strategy duration (max)	1,440 min (24 hours)	—
GetLatestConfiguration TPS	1,000	Contact support	Rarely hit with agent caching
StartConfigurationSession TPS	500	Contact support	Can be hit during mass cold starts
Configuration token validity	24 hours	—
Minimum poll interval (SDK)	15 seconds	—
Lambda validator timeout	15 seconds (hard limit)	—	Includes cold start time
Revert window after deployment	72 hours	—

Check Service Quotas for your account limits: aws service-quotas list-service-quotas --service-code appconfig. Note: Some limits (monitors per environment, validators per profile, feature flag attributes) are hard limits documented in the user guide and do not appear in the Service Quotas API.

Pricing

AppConfig uses pay-as-you-go pricing:

• $0.0008 per configuration received
• $0.0000002 per API request
• Hosted configuration store: No cost for storage
• AppConfig Agent reduces costs by caching locally and minimizing API calls

Use the AppConfig Agent (Lambda extension, container sidecar, or EC2 daemon) to optimize costs — it caches configurations locally and only polls for updates at the configured interval.

Cost estimation example: A Lambda function invoked 1M times/day with a 45-second poll interval:

• The extension polls ~1,920 times/day per execution environment (86,400s ÷ 45s)
• With 50 concurrent execution environments: ~96,000 polls/day → ~2.88M polls/month
• At $0.0000002/request: ~$0.58/month for API requests
• Configuration received only when content changes (not on every poll), so configuration received charges depend on deployment frequency, not invocation count
• Deploying once/day to 50 environments: 50 × 30 = 1,500 configurations received/month → ~$1.20/month
• Total: ~$1.78/month for this workload

Pricing is subject to change. Check the AWS AppConfig pricing page for current rates.

Troubleshooting Quick Reference

Error	Cause	Solution
BadRequestException on deploy	Configuration fails validation	Fix configuration against the validator schema (JSON Schema draft-04)
ConflictException on deploy	Another deployment is in progress	Wait for the current deployment or use aws appconfig stop-deployment
ResourceNotFoundException	Wrong application, environment, or profile ID, or wrong region	Verify IDs with aws appconfig list-applications and ensure --region matches the deployment region
Invalid base64 on create-hosted-configuration-version	Raw JSON passed to --content	Use fileb:// prefix: --content fileb://config.json or --content fileb://<(echo -n '...')
Lambda extension returns stale config	Cache not refreshed	Check AWS_APPCONFIG_EXTENSION_POLL_INTERVAL_SECONDS (default 45s)
Deployment rolled back	CloudWatch alarm triggered during deployment or bake time	Check the alarm metric to identify the root cause
Deployment stuck in BAKING	Alarm in INSUFFICIENT_DATA — no metric data during bake	Set TreatMissingData: notBreaching on the alarm
Feature flag evaluates to default	Flag not found, enabled: false, or context mismatch	Verify flag key (case-sensitive), enabled status, and targeting rule context
Connection refused on localhost:2772	Lambda extension layer not added	Add the AppConfig extension layer ARN for your region and architecture
AccessDeniedException	Missing IAM permissions	Add appconfig:StartConfigurationSession and appconfig:GetLatestConfiguration

For detailed troubleshooting, see troubleshooting.md.

Configuration

Authentication Setup

This skill requires AWS credentials configured on the host machine:

1. Install AWS CLI: Follow the AWS CLI installation guide
2. Configure credentials: Run aws configure or set up named profiles in ~/.aws/credentials
3. Set environment variables (if not using the default profile):
   • AWS_PROFILE - Named profile to use
   • AWS_REGION - Target AWS region (critical — AppConfig resources are regional)
4. Verify access: Run aws sts get-caller-identity to confirm credentials are valid

Important: Always ensure AWS_REGION is set or pass --region to every AWS CLI command. AppConfig resources are regional — CLI commands will fail with ResourceNotFoundException if the region doesn't match where the resources were created. When deploying with SAM, the region is set in samconfig.toml, but subsequent aws appconfig CLI commands (e.g., creating new configuration versions) must target the same region explicitly.

Required IAM Permissions

For Lambda functions reading configuration at runtime (least-privilege):

{
  "Effect": "Allow",
  "Action": [
    "appconfig:StartConfigurationSession",
    "appconfig:GetLatestConfiguration"
  ],
  "Resource": "arn:aws:appconfig:REGION:ACCOUNT:application/APP_ID/environment/ENV_ID/configuration/PROFILE_ID"
}

SAM CLI Setup

1. Install SAM CLI: Follow the SAM CLI installation guide
2. Verify: Run sam --version