AWS CloudFront ExecModule

Overview

AwsCloudFrontModule brings bounded AWS CloudFront distribution discovery, configuration inspection, invalidation tracking, origin access control inventory, and explicitly confirmed cache invalidations into ValkyrAI workflows.

The module uses ValkyrAI's native map ABI, annotation-backed Workflow Studio discovery, and a verified IntegrationAccount. Workflow input never accepts AWS keys, session tokens, authorization headers, endpoint overrides, raw SDK requests, complete distribution replacement documents, certificate material, private keys, signed URL keys, or arbitrary CloudFront policy documents.

This first release is designed for release automation, CDN inventory, post-deployment verification, stale-asset remediation, and security review of origin access controls. Reads may retry transient failures with bounded backoff. An invalidation requires an exact distribution, one to 1,000 reviewed absolute paths, a stable caller reference, and explicit confirmation. The module sends that mutation once so an ambiguous provider response can be reconciled before any replay.

Usage

1. Create or select a least-privilege AWS identity for the exact CloudFront actions the workflow needs.
2. Store the access-key pair in an AWS IntegrationAccount.
3. Verify the account and ensure its status is READY.
4. Add AwsCloudFrontModule and bind the account through ExecModuleConfig.authConfig.integrationAccount.
5. Choose an operation and provide only the relevant exact identifiers or list bounds.
6. Before creating an invalidation, inspect the distribution, review every path and the expected cache/cost impact, choose a durable caller reference, then set confirmInvalidation to true.

CloudFront is a global AWS service. The module does not accept a caller-controlled region or endpoint; it signs requests through the standard global CloudFront control plane.

Never place credentials in module input. Credential-shaped fields and endpoint overrides are rejected before any AWS request.

Inputs

Common and pagination inputs

Input	Type	Required	Default	Purpose
operation	string	Yes	—	One supported CloudFront operation.
marker	string	No	—	Opaque provider continuation marker for list operations.
limit	integer	For list operations	100	Total result bound from 1 to 1,000.
returnAll	boolean	For list operations	false	Follow provider pages until limit or a provider boundary.

Resource inputs

Input	Operations	Rules
distributionId	Distribution and invalidation operations	Exact bounded CloudFront distribution identifier.
invalidationId	get_invalidation	Exact invalidation identifier within the selected distribution.
originAccessControlId	get_origin_access_control	Exact modern origin access control identifier.

Invalidation inputs

Input	Type	Rules
paths	array	One to 1,000 unique absolute cache paths. Every value must begin with /; wildcards use CloudFront path syntax.
callerReference	string	Required stable reference, at most 128 characters, chosen by the caller for reconciliation and replay protection.
confirmInvalidation	boolean	Must be true to send one invalidation request.

Path /index.html targets one object. Path /assets/* can affect many cached objects and may increase invalidation cost. Treat broad wildcards as a reviewed operational decision rather than a convenience default.

Outputs

Successful execution uses a stable envelope:

Output	Meaning
status	success or error.
operation	Normalized operation name.
attempts	Provider calls, including pages and safe read retries.
resultType	Distribution, configuration, invalidation, or origin access control family.
items / count	Bounded normalized list results.
pages	Provider pages consumed.
hasMore / nextMarker	Whether and where provider pagination may continue.
data	Bounded metadata for an exact distribution, config, invalidation, or origin access control.
requestId	Safe AWS request reference when available.
error	Safe code, message, HTTP status, and retryability.

Distribution output includes bounded identity, deployment status, domain, aliases, origins, HTTP version, price class, enablement, IPv6, Web ACL reference, and cache-policy linkage where available. It excludes credentials, complete certificate configuration, private material, raw provider objects, and unbounded nested configuration.

IntegrationAccount Requirements

The bound account must be verified, have status READY, and supply its AWS access-key ID through apiKey plus its secret access key through password. The module never serializes those values into output or logs.

Grant only the operations used by the workflow:

cloudfront:ListDistributions
cloudfront:GetDistribution
cloudfront:GetDistributionConfig
cloudfront:ListInvalidations
cloudfront:GetInvalidation
cloudfront:CreateInvalidation
cloudfront:ListOriginAccessControls
cloudfront:GetOriginAccessControl

Separate read-only inventory identities from invalidation-capable identities when practical. Scope invalidation permission to reviewed distribution resources where the current AWS authorization model supports it. Do not grant distribution create, update, disable, or delete permissions for this release.

Configuration

The module uses ExecModuleConfig for IntegrationAccount binding, retry ceiling, and workflow policy. It does not accept endpoint overrides, custom signing hosts, inline IAM policies, cross-account role material, complete distribution configuration documents, TLS key material, signed URL keys, or CloudFront function code.

Reads use at most five attempts, bounded by configured maxAttempts. AWS SDK retries are disabled so the module owns the visible attempt count. create_invalidation always uses one provider call, even when AWS returns a transient error.

Operations

Operation	Behavior	Side effect
list_distributions	Lists bounded distribution summaries, aliases, origins, deployment state, and delivery settings.	None; provider read quota applies.
get_distribution	Reads bounded status and selected configuration for one exact distribution.	None.
get_distribution_config	Reads selected configuration plus its ETag for review and change planning.	None.
list_invalidations	Lists bounded invalidation history for one exact distribution.	None.
get_invalidation	Reads status, caller reference, and paths for one exact invalidation.	None.
create_invalidation	Submits one confirmed path invalidation with a caller reference.	External cache-control write; quota and charges can apply.
list_origin_access_controls	Lists modern OAC identity, origin type, and signing behavior.	None.
get_origin_access_control	Reads one OAC plus its ETag.	None.

Errors and Failure Modes

Code	Meaning	Retry guidance
VALIDATION_ERROR	An identifier, marker, bound, path set, caller reference, field, or confirmation failed locally.	Correct input; no AWS call occurred.
UNSUPPORTED_OPERATION	The requested CloudFront capability is outside this release.	Select one documented operation.
INTEGRATION_ACCOUNT_ERROR	The account is missing, unverified, not READY, or incomplete.	Repair the account binding.
AWS_CLOUDFRONT_HTTP_400	AWS rejected the identifier, marker, invalidation path, caller reference, or request state.	Usually no; inspect exact input and existing invalidations.
AWS_CLOUDFRONT_HTTP_403	IAM denied the action or resource.	Add only the missing least-privilege permission.
AWS_CLOUDFRONT_HTTP_404	The selected distribution, invalidation, or origin access control was not found.	Confirm account, partition, and exact identifier.
AWS_CLOUDFRONT_HTTP_429 / 500 / 502 / 503 / 504	Throttling or transient provider pressure.	Reads retry; invalidation writes require reconciliation first.
NETWORK_ERROR	AWS could not be reached.	Reads may retry; inspect invalidation history before replaying a write.
EXECUTION_ERROR	An unexpected local failure was safely normalized.	Use logs and request references; secrets remain redacted.

AWS may accept an invalidation before the client observes a timeout. A retryable status is never permission to blindly submit another invalidation. Search the selected distribution's invalidation history for the caller reference and reviewed path set first.

Example

This example invalidates two release-critical paths after a production asset publish:

{
  "operation": "create_invalidation",
  "distributionId": "E1EXAMPLE",
  "paths": [
    "/index.html",
    "/assets/release.js"
  ],
  "callerReference": "release-20261024T0300Z",
  "confirmInvalidation": true
}

Expected normalized result:

{
  "status": "success",
  "operation": "create_invalidation",
  "attempts": 1,
  "resultType": "invalidation",
  "data": {
    "id": "I123EXAMPLE",
    "status": "InProgress",
    "createTime": "2026-10-24T03:15:00Z",
    "callerReference": "release-20261024T0300Z",
    "paths": [
      "/index.html",
      "/assets/release.js"
    ]
  },
  "requestId": "example-request-id"
}

A workflow can poll get_invalidation with a bounded cadence until the provider reports Completed, then perform an external content check. The invalidation response confirms control-plane state; it does not prove that every viewer, resolver, or intermediate cache has observed new content.

Notes

• Pagination: List operations expose nextMarker; returnAll: true follows at most 100 provider pages and never returns more than limit items.
• Global service: CloudFront has a global control plane. This module does not accept region selection or endpoint overrides.
• Eventual consistency: Distribution updates and invalidations propagate asynchronously. Treat InProgress and Deployed as provider control-plane states, then verify the exact public asset independently.
• Rate limits and cost: AWS quotas apply to control-plane requests. Invalidation charges and free-tier treatment depend on the account and current AWS pricing. Keep path sets narrow and avoid tight polling loops.
• Paths: /directory/* is broader than /directory/file.js. Validate wildcard scope before confirmation. Query strings and cache-key policy determine whether a path clears all relevant variants.
• Configuration reads: get_distribution_config returns selected safe fields and an ETag, not a mutation-ready replacement document.
• Origin security: OAC reads show signing posture but do not prove the origin bucket, service, network policy, or resource policy is correctly restricted. Review those resources separately.
• Idempotency: Reads are repeatable within provider freshness limits. Invalidations require a caller reference and are not automatically retried.
• Destructive behavior: No distribution, behavior, policy, function, key, certificate, or OAC delete/update operation is exposed. Invalidations remove cached copies from edge delivery and can create operational load and cost, but do not delete origin objects.
• Deferred capabilities: Distribution create/update/disable/delete, cache/origin/response-header policy lifecycle, CloudFront Functions and Lambda@Edge, key groups, public keys, signed URLs/cookies, real-time logs, monitoring subscriptions, continuous deployment, tenants, VPC origins, OAC writes, legacy OAI writes, tags, aliases, Web ACL association, and bulk account-wide mutation are intentionally deferred.
• Credential boundary: Live AWS behavior remains unverified until an authorized least-privilege non-production account and reviewed CloudFront resources are supplied.
• Functional reference: n8n's AWS integration patterns provide the familiar credential, resource, operation, and pagination model. ValkyrAI applies that model through IntegrationAccount, strict per-operation inputs, bounded normalized output, explicit invalidation confirmation, and mutation replay safety.
• Runtime boundary: Merged source and published documentation do not update the deployed Workflow Studio catalog until a ValkyrAI backend release exposes AwsCloudFrontModule through /v1/modules/metadata.

Related documentation

• AWS CloudFront API Reference
• AWS CloudFront invalidation guidance
• AWS CloudFront IAM policy examples
• AWS X-Ray ExecModule