AWS AppConfig ExecModule

Overview

AwsAppConfigModule brings bounded AWS AppConfig discovery, hosted-configuration, and deployment operations into ValkyrAI workflows. It can inventory applications, environments, configuration profiles, hosted versions, and deployments; reveal one explicitly approved hosted version; create one concurrency-guarded hosted version; start a reviewed deployment; and stop or revert an exact deployment.

AWS AppConfig separates changing operational behavior from application deployment. Common uses include feature flags, allow/block lists, throttling limits, logging levels, and other dynamic settings. ValkyrAI keeps these changes inside the native ExecModule ABI with a verified IntegrationAccount, strict field allowlists, confidential output, explicit confirmations, bounded pagination/content, and deterministic reconciliation after ambiguous provider failures.

The connector implements eleven operations:

• list_applications and get_application discover AppConfig namespaces.
• list_environments and list_configuration_profiles discover deployment targets and configuration sources.
• list_hosted_versions, get_hosted_version, and create_hosted_version govern the hosted configuration store.
• list_deployments, get_deployment, start_deployment, and stop_deployment govern progressive rollout state.

n8n's AWS nodes are the functional workflow reference for operation-driven configuration, reusable AWS credentials, AI-tool compatibility, and custom service calls when a dedicated operation is unavailable. ValkyrAI adds a native AppConfig contract with resource bounds, reveal/mutation confirmations, read-only retries, single-attempt writes, and stable normalized receipts.

Usage

1. Identify the exact AppConfig application, environment, configuration profile, and deployment strategy the workflow may use.
2. Create a least-privilege AWS principal for only those AppConfig resources and actions.
3. Store its access key ID and secret access key in an AWS IntegrationAccount; verify it and keep it in READY status.
4. Add AwsAppConfigModule and bind that account through ExecModuleConfig.authConfig.integrationAccount.
5. Run the list/read operations first and capture provider IDs rather than guessing names or IDs.
6. For hosted configuration creation, base64-encode at most 1 MiB, supply a MIME type, and normally provide latestVersionNumber as an optimistic concurrency guard.
7. Set the exact confirmation field to true for configuration content reads and every mutation.
8. After a timeout or network failure on a mutation, reconcile the hosted-version or deployment state before replaying anything.

Never place an AWS access key, secret key, session token, password, or credentials object in module input. Raw credential-shaped fields are rejected before network access. Configuration bytes and deployment topology are confidential and belong only in ACL-scoped workflow state.

Inputs

Name	Type	Required for	Default	Constraints
operation	string	Every execution	None	One of the eleven documented operations.
region	string	Every execution	None	Valid AWS region such as us-west-2.
nextToken	string	Optional list field	None	Opaque provider token, at most 4,096 characters.
limit	integer	Optional list field	100	Total bound from 1 through 10,000.
returnAll	boolean	Optional list field	false	Follow pages until limit, exhaustion, or 100 pages.
applicationId	string	All operations except list_applications	None	Lowercase AWS AppConfig ID, 4-7 alphanumeric characters.
environmentId	string	Deployment operations	None	Lowercase AWS AppConfig ID, 4-7 alphanumeric characters.
configurationProfileId	string	Hosted-version/start operations	None	Lowercase AWS AppConfig ID, 4-7 alphanumeric characters.
profileType	string	Optional profile list filter	None	Bounded provider type such as AWS.AppConfig.FeatureFlags.
versionNumber	integer	get_hosted_version	None	Positive hosted version number.
versionLabel	string	Optional hosted version filter/label	None	1-64 letters, digits, period, underscore, or hyphen; begins and ends alphanumeric.
contentBase64	string	create_hosted_version	None	Valid base64 decoding to 1-1,048,576 bytes.
contentType	string	create_hosted_version	None	MIME type up to 255 characters, for example application/json.
latestVersionNumber	integer	Optional create guard	None	Positive number; AWS rejects creation if the latest version changed.
description	string	Optional create/start field	None	At most 1,024 characters.
deploymentNumber	integer	get_deployment, stop_deployment	None	Positive deployment number.
deploymentStrategyId	string	start_deployment	None	AppConfig strategy ID or predefined strategy name.
configurationVersion	string	start_deployment	None	Existing hosted/external version or version label.
kmsKeyIdentifier	string	Optional deployment encryption	None	Customer-managed KMS key ID or ARN, at most 2,048 characters.
tags	object	Optional start tags	{}	Up to 50 string pairs; aws: keys are rejected.
allowRevert	boolean	Optional stop behavior	false	Allows AWS to revert an already completed deployment when supported.
confirmRevealConfiguration	boolean	get_hosted_version	false	Must be exactly true before bytes are returned.
confirmCreateHostedVersion	boolean	create_hosted_version	false	Must be exactly true.
confirmStartDeployment	boolean	start_deployment	false	Must be exactly true.
confirmStopDeployment	boolean	stop_deployment	false	Must be exactly true; covers stop and optional revert.

Unexpected fields fail before provider access. contentBase64, latestVersionNumber, tags, and confirmation fields are accepted only by the operations that own them.

Outputs

Every call returns stable status, operation, and attempts fields.

Name	Type	When present	Description
status	string	Always	success or error.
operation	string	Always	Normalized operation.
attempts	integer	Always	Provider calls including pages and retry-safe reads.
resultType	string	Success	Application, environment, profile, version, deployment, or mutation family.
items	array	List success	Bounded normalized resources.
count	integer	List success	Number of returned resources.
pages	integer	List success	Provider pages consumed.
hasMore	boolean	List success	Whether AWS returned another token.
nextToken	string	Another page exists	Opaque continuation token.
data	object	Read/mutation success	Normalized resource, content, or acceptance receipt.
requestId	string	AWS supplies one	Bounded provider reference for reconciliation.
error	object	Failure	Safe {code, message, httpStatus?, retryable} details.

Application results contain IDs, names, and descriptions. Environment results also expose state and monitor count. Configuration-profile summaries expose source URI, type, and validator types. Hosted-version metadata exposes version number, content type, version label, and KMS ARN; only confirmed get_hosted_version returns contentBase64. Deployment results expose exact identifiers, state, percentage, version, and timestamps. Mutation receipts never echo submitted configuration bytes, tags, credentials, or provider exception text.

IntegrationAccount Requirements

Bind one AWS IntegrationAccount through the normalized ExecModule authentication relationship:

Field	Requirement
Provider	Amazon Web Services / AppConfig
status	Must be READY.
verified	Must be true.
apiKey SecureField	AWS access key ID.
password SecureField	AWS secret access key.

Grant only the actions needed by the reviewed workflow:

• Discovery: appconfig:ListApplications, appconfig:GetApplication, appconfig:ListEnvironments, and appconfig:ListConfigurationProfiles.
• Hosted configuration reads: appconfig:ListHostedConfigurationVersions and appconfig:GetHostedConfigurationVersion.
• Hosted configuration writes: appconfig:CreateHostedConfigurationVersion for approved profiles.
• Deployment reads: appconfig:ListDeployments and appconfig:GetDeployment.
• Deployment writes: appconfig:StartDeployment and appconfig:StopDeployment for approved applications, environments, profiles, and strategies.
• Encryption: add only the necessary KMS actions and key conditions when a customer-managed key is used.

Use IAM resource conditions, organizational service-control policies, separate accounts/environments, AppConfig validators, CloudWatch monitors, and human approval to reduce blast radius.

Configuration

The awsAccount relationship is the only credential configuration. Operation, resource, version, content, pagination, and safety fields belong in mapped input or module parameters.

{
  "version": "1.0.0",
  "authConfig": {
    "authStrategy": 1,
    "integrationAccount": "integration-account:aws-appconfig-production"
  },
  "payloadConfig": {
    "parameters": "{\"operation\":\"start_deployment\",\"region\":\"us-west-2\"}"
  }
}

The relationship value is illustrative. Persisted workflows bind the generated IntegrationAccount relationship, never plaintext credentials.

Operations

Operation	Provider behavior	Side effect and retry behavior
list_applications	Lists bounded application namespaces.	Read-only; each page retries transient failures.
get_application	Reads one exact application.	Read-only; bounded retry.
list_environments	Lists environments for one application.	Read-only; bounded pagination/retry.
list_configuration_profiles	Lists configuration profiles, optionally by provider type.	Read-only; bounded pagination/retry.
list_hosted_versions	Lists hosted-version metadata without content bytes.	Read-only; bounded pagination/retry.
get_hosted_version	Returns one hosted version and base64 content after explicit reveal confirmation.	Sensitive read; bounded retry.
create_hosted_version	Creates one hosted version from bounded base64 content.	Confirmed write; exactly one attempt. Use latestVersionNumber to prevent stale writes.
list_deployments	Lists deployments for one application/environment.	Read-only; bounded pagination/retry.
get_deployment	Reads one exact deployment number and state.	Read-only; bounded retry.
start_deployment	Starts one deployment of an existing configuration version using an existing strategy.	Confirmed external mutation; exactly one attempt.
stop_deployment	Stops an exact deployment or requests supported reversion.	Confirmed potentially destructive mutation; exactly one attempt.

Errors and Failure Modes

Code	Typical cause	Retryable	Resolution
VALIDATION_ERROR	Missing/malformed ID, region, payload, version, tag, bound, or confirmation.	No	Correct the named input; no provider request was sent.
UNSUPPORTED_OPERATION	Unknown operation.	No	Select a documented operation.
INTEGRATION_ACCOUNT_ERROR	Account missing, unverified, not READY, or missing key material.	No	Repair and bind the AWS account.
AWS_APPCONFIG_HTTP_400	Invalid artifact relationship, validation failure, stale version guard, or deployment conflict.	Reads retry only selected transient codes	Inspect exact AppConfig state and request ID.
AWS_APPCONFIG_HTTP_403	IAM, KMS, SCP, or resource policy denied the request.	No	Grant only the missing action or revise the workflow.
AWS_APPCONFIG_HTTP_404	Application, environment, profile, version, strategy, or deployment is absent.	No	Reconcile the exact provider IDs.
AWS_APPCONFIG_HTTP_409	A deployment or version transition conflicts with current state.	No automatic mutation retry	Read current state before deciding whether to retry.
AWS_APPCONFIG_HTTP_429 / 500 / 503	Throttle or transient provider pressure.	Reads retry; writes remain single-attempt	Reconcile version/deployment state before replay.
NETWORK_ERROR	DNS, TLS, timeout, or connectivity failure.	Reads retry; writes report ambiguity	Treat provider acceptance as unknown until state is checked.
EXECUTION_ERROR	Unexpected bounded runtime failure.	No automatic replay	Preserve operation and request evidence for investigation.

Provider exception messages are never copied into workflow output. This prevents credentials, configuration values, resource topology, and policy details from leaking through failures.

Example

Start a reviewed deployment of hosted configuration version 12:

{
  "operation": "start_deployment",
  "region": "us-west-2",
  "applicationId": "a1b2c3",
  "environmentId": "d4e5f6",
  "configurationProfileId": "g7h8i9",
  "configurationVersion": "12",
  "deploymentStrategyId": "AppConfig.Linear50PercentEvery30Seconds",
  "description": "Reviewed checkout flag rollout",
  "tags": {
    "change": "CHG-1042",
    "owner": "platform"
  },
  "confirmStartDeployment": true
}

Expected result shape:

{
  "status": "success",
  "operation": "start_deployment",
  "attempts": 1,
  "resultType": "deployment_start",
  "data": {
    "accepted": true,
    "applicationId": "a1b2c3",
    "environmentId": "d4e5f6",
    "configurationProfileId": "g7h8i9",
    "configurationVersion": "12",
    "deploymentNumber": 42,
    "state": "BAKING"
  },
  "requestId": "aws-request-reference"
}

The receipt proves only that AWS accepted the call. Poll get_deployment until a terminal state, and preserve AppConfig validator/monitor evidence before depending on the new configuration.

Notes

• Pagination: list operations accept an opaque nextToken, cap individual pages at 50, and stop after the caller's limit, provider exhaustion, or 100 pages.
• Rate limits: the AWS SDK's internal retries are disabled. ValkyrAI applies bounded retries only to reads and honors the configured ExecModule retry count from 1 through 5.
• API limits: hosted configuration input is capped at 1 MiB by this connector even where a tenant quota is higher. Application, environment, and profile creation remain infrastructure-as-code responsibilities.
• Idempotency: create_hosted_version supports AWS's latestVersionNumber concurrency check but still runs once. Deployment starts/stops run once and require exact state reconciliation after an ambiguous response.
• Destructive behavior: stop_deployment may interrupt a rollout; allowRevert can request reversion of a completed deployment. Both require confirmStopDeployment: true.
• Content handling: configuration bytes are accepted and returned only as base64, never logged, never included in toString(), and never echoed after creation.
• Deployment safety: prefer AppConfig validators, progressive strategies, bake time, CloudWatch alarms, and separate environments instead of immediate broad rollout.
• Deferred scope: application/environment/profile creation or deletion, deployment-strategy lifecycle, extension lifecycle, account settings, tags outside deployment start, dynamic extension parameters, and AppConfig Data polling are intentionally excluded.
• External verification: repository tests use deterministic transports and make no AWS call. Provider behavior requires a separately authorized least-privilege AWS account and reviewed AppConfig resources.