AWS.AppConfig reference

Application

Source: src/AWS/AppConfig/Application.ts

An AWS AppConfig application — the top-level container that groups the environments and configuration profiles for one application’s configuration.

Application: Creating an Application

Basic Application

const app = yield* AppConfig.Application("MyApp", {
  description: "Configuration for my service",
});

Named Application with Tags

const app = yield* AppConfig.Application("MyApp", {
  applicationName: "my-service",
  tags: { team: "platform" },
});

ConfigurationProfile

Source: src/AWS/AppConfig/ConfigurationProfile.ts

An AWS AppConfig configuration profile — describes where the configuration data lives (the AppConfig hosted store, S3, SSM, Secrets Manager, or CodePipeline) and how to validate it.

ConfigurationProfile: Creating a Configuration Profile

Hosted Configuration Profile

const profile = yield* AppConfig.ConfigurationProfile("Settings", {
  applicationId: app.applicationId,
  locationUri: "hosted",
});

S3-sourced Profile with a JSON Schema Validator

const profile = yield* AppConfig.ConfigurationProfile("Settings", {
  applicationId: app.applicationId,
  locationUri: "s3://my-bucket/config.json",
  retrievalRoleArn: role.roleArn,
  validators: [{ type: "JSON_SCHEMA", content: schemaJson }],
});

CreateHostedConfigurationVersion

Source: src/AWS/AppConfig/CreateHostedConfigurationVersion.ts

Write a new configuration version to the AppConfig hosted store from a Lambda (or other AWS runtime). Pairs with StartDeployment to build runtime feature-flag/configuration management services: write the new content, then roll it out.

Provide AppConfig.CreateHostedConfigurationVersionHttp on the hosting function’s Effect to implement the binding.

CreateHostedConfigurationVersion: Writing Configuration at Runtime

const createVersion = yield* AppConfig.CreateHostedConfigurationVersion(
  app,
  profile,
);
const version = yield* createVersion({
  Content: JSON.stringify({ featureX: false }),
  ContentType: "application/json",
});
// version.VersionNumber -> 2

Deployment

Source: src/AWS/AppConfig/Deployment.ts

An AWS AppConfig deployment — releases a configuration version to an environment following a deployment strategy. Deployments are immutable and asynchronous: the provider starts the deployment and waits (bounded) for it to reach a terminal state. Any change to the deployed version, strategy, or target creates a new deployment (a replacement). Use an all-at-once strategy (duration 0, bake 0) for a near-instant rollout.

Deployment: Deploying a Configuration

const deployment = yield* AppConfig.Deployment("Rollout", {
  applicationId: app.applicationId,
  environmentId: env.environmentId,
  deploymentStrategyId: strategy.deploymentStrategyId,
  configurationProfileId: profile.configurationProfileId,
  configurationVersion: String(version.versionNumber),
});

DeploymentEventSource

Source: src/AWS/AppConfig/DeploymentEventSource.ts

Event source connecting AppConfig deployment notifications to the hosting compute. The contract is a Binding.Service; the Lambda implementation layer is Lambda.AppConfigDeploymentEventSource (extension + association + invoke role at deploy time, payload dispatch at runtime). Consume it through the consumeDeploymentEvents helper.

DeploymentEventSource: Consuming Deployment Events

export default MyFunction.make(
  { main: import.meta.url },
  Effect.gen(function* () {
    const app = yield* AppConfig.Application("App", {});
    const env = yield* AppConfig.Environment("Env", {
      applicationId: app.applicationId,
    });

    yield* AppConfig.consumeDeploymentEvents(env, (events) =>
      events.pipe(
        Stream.runForEach((event) =>
          Effect.log(`deployment event: ${event.Type}`),
        ),
      ),
    );
  }).pipe(Effect.provide(Lambda.AppConfigDeploymentEventSource)),
);

DeploymentStrategy

Source: src/AWS/AppConfig/DeploymentStrategy.ts

An AWS AppConfig deployment strategy — defines how a configuration version rolls out to an environment: the total duration, the per-interval growth, and the final bake time during which alarms can trigger a rollback.

DeploymentStrategy: Creating a Deployment Strategy

All-At-Once (instant, no bake)

const strategy = yield* AppConfig.DeploymentStrategy("Fast", {
  deploymentDuration: 0,
  growthFactor: 100,
  finalBakeTime: 0,
  replicateTo: "NONE",
});

Linear rollout over 10 minutes

const strategy = yield* AppConfig.DeploymentStrategy("Linear", {
  deploymentDuration: "10 minutes",
  growthFactor: 25,
  growthType: "LINEAR",
  finalBakeTime: "5 minutes",
});

Environment

Source: src/AWS/AppConfig/Environment.ts

An AWS AppConfig environment — a deployment group of AppConfig targets (e.g. Beta, Production) within an application. CloudWatch alarms attached via monitors trigger an automatic rollback if they fire during a deployment.

Environment: Creating an Environment

Basic Environment

const app = yield* AppConfig.Application("MyApp", {});
const env = yield* AppConfig.Environment("Prod", {
  applicationId: app.applicationId,
});

Environment with Rollback Alarm

const env = yield* AppConfig.Environment("Prod", {
  applicationId: app.applicationId,
  monitors: [{ alarmArn: alarm.alarmArn, alarmRoleArn: role.roleArn }],
});

Extension

Source: src/AWS/AppConfig/Extension.ts

An AWS AppConfig extension — a set of actions AppConfig performs at specific points of the configuration workflow (before a version is created, before/while/after a deployment). Actions can invoke Lambda functions, publish to SNS/SQS, or emit EventBridge events.

Associate the extension with an application, environment, or configuration profile using ExtensionAssociation.

Extension: Creating an Extension

Notify a Lambda when a deployment completes

const extension = yield* AppConfig.Extension("DeployHook", {
  actions: {
    ON_DEPLOYMENT_COMPLETE: [
      {
        name: "notify",
        uri: fn.functionArn,
        roleArn: role.roleArn,
      },
    ],
  },
});

Validate content before a deployment starts

const extension = yield* AppConfig.Extension("PreflightCheck", {
  description: "Reject deployments outside business hours",
  actions: {
    PRE_START_DEPLOYMENT: [
      { name: "preflight", uri: fn.functionArn, roleArn: role.roleArn },
    ],
  },
});

ExtensionAssociation

Source: src/AWS/AppConfig/ExtensionAssociation.ts

An AWS AppConfig extension association — attaches an Extension to an application, environment, or configuration profile so the extension’s actions fire for that resource’s workflow events.

ExtensionAssociation: Associating an Extension

Attach an Extension to an Application

const association = yield* AppConfig.ExtensionAssociation("Hook", {
  extensionIdentifier: extension.extensionId,
  resourceIdentifier: app.applicationArn,
});

Attach with Parameter Values

const association = yield* AppConfig.ExtensionAssociation("Hook", {
  extensionIdentifier: extension.extensionId,
  resourceIdentifier: env.environmentArn,
  parameters: { topicArn: topic.topicArn },
});

GetConfiguration

Source: src/AWS/AppConfig/GetConfiguration.ts

Fetch the live, deployed configuration for a Lambda (or other AWS runtime) via the AppConfig data plane. Backed by StartConfigurationSession + GetLatestConfiguration: the binding starts a session on first use, caches the poll token, and returns the latest content on each call.

Provide AppConfig.GetConfigurationHttp on the hosting function’s Effect (Effect.provide(AppConfig.GetConfigurationHttp)) to satisfy the binding.

GetConfiguration: Reading Live Configuration

const getConfig = yield* AppConfig.GetConfiguration(app, env, profile);
const { content, contentType } = yield* getConfig();
const settings = JSON.parse(content ?? "{}");

GetDeployment

Source: src/AWS/AppConfig/GetDeployment.ts

Read an AppConfig deployment’s status from a Lambda (or other AWS runtime) — poll a rollout started with StartDeployment until it reaches a terminal state (COMPLETE, ROLLED_BACK, REVERTED).

Provide AppConfig.GetDeploymentHttp on the hosting function’s Effect to implement the binding.

GetDeployment: Deploying Configuration at Runtime

const getDeployment = yield* AppConfig.GetDeployment(app, env);
const deployment = yield* getDeployment({ DeploymentNumber: 2 });
// deployment.State, deployment.PercentageComplete

HostedConfigurationVersion

Source: src/AWS/AppConfig/HostedConfigurationVersion.ts

An AWS AppConfig hosted configuration version — the actual configuration content stored in the AppConfig hosted store. Versions are immutable: each change to the content produces a new version (a replacement), and its versionNumber is what you deploy through a Deployment.

HostedConfigurationVersion: Creating a Hosted Configuration Version

const version = yield* AppConfig.HostedConfigurationVersion("V1", {
  applicationId: app.applicationId,
  configurationProfileId: profile.configurationProfileId,
  content: JSON.stringify({ featureX: true }),
  contentType: "application/json",
});
// version.versionNumber -> 1

StartDeployment

Source: src/AWS/AppConfig/StartDeployment.ts

Start an AppConfig deployment from a Lambda (or other AWS runtime) — roll a configuration version out to an environment following a deployment strategy. Pairs with CreateHostedConfigurationVersion to build runtime feature-flag/configuration management services.

Provide AppConfig.StartDeploymentHttp on the hosting function’s Effect to implement the binding.

StartDeployment: Deploying Configuration at Runtime

const startDeployment = yield* AppConfig.StartDeployment(
  app,
  env,
  profile,
  strategy,
);
const deployment = yield* startDeployment({
  ConfigurationVersion: "2",
});
// deployment.DeploymentNumber, deployment.State ("DEPLOYING", ...)

StopDeployment

Source: src/AWS/AppConfig/StopDeployment.ts

Stop (or revert) an AppConfig deployment from a Lambda (or other AWS runtime). Stopping an in-progress rollout rolls it back; with AllowRevert: true a completed deployment can be reverted within 72 hours.

Provide AppConfig.StopDeploymentHttp on the hosting function’s Effect to implement the binding.

StopDeployment: Deploying Configuration at Runtime

const stopDeployment = yield* AppConfig.StopDeployment(app, env);
yield* stopDeployment({ DeploymentNumber: 2 });

ValidateConfiguration

Source: src/AWS/AppConfig/ValidateConfiguration.ts

Validate a configuration version against a configuration profile’s validators from a Lambda (or other AWS runtime). Pairs with CreateHostedConfigurationVersion + StartDeployment: write the new content, validate it, then roll it out. Fails with a typed BadRequestException when a validator rejects the content; succeeds with an empty response when validation passes (including when the profile has no validators).

Provide AppConfig.ValidateConfigurationHttp on the hosting function’s Effect to implement the binding.

ValidateConfiguration: Writing Configuration at Runtime

const validate = yield* AppConfig.ValidateConfiguration(app, profile);
yield* validate({ ConfigurationVersion: "2" });