Skip to content

CloudFront

CloudFront management-plane and local content-delivery emulation. Supports distribution lifecycle, cache policies, origin request policies, response headers policies, origin access controls, origin access identities, public keys, trusted key groups, CloudFront Functions, key value stores, invalidations, tagging, and viewer delivery from S3 or custom origins for every CloudFront viewer method (GET, HEAD, OPTIONS, POST, PUT, PATCH and DELETE).

Protocol: REST XML API version: 2020-05-31 Endpoint prefix: cloudfront Namespace: http://cloudfront.amazonaws.com/doc/2020-05-31/ Global service — ARNs contain no region segment.

Supported Operations

Distributions

Operation Method Path
CreateDistribution POST /2020-05-31/distribution
CreateDistributionWithTags POST /2020-05-31/distribution?WithTags
GetDistribution GET /2020-05-31/distribution/{Id}
GetDistributionConfig GET /2020-05-31/distribution/{Id}/config
UpdateDistribution PUT /2020-05-31/distribution/{Id}/config
DeleteDistribution DELETE /2020-05-31/distribution/{Id}
ListDistributions GET /2020-05-31/distribution
AssociateAlias PUT /2020-05-31/distribution/{TargetDistributionId}/associate-alias

Invalidations

Operation Method Path
CreateInvalidation POST /2020-05-31/distribution/{Id}/invalidation
GetInvalidation GET /2020-05-31/distribution/{Id}/invalidation/{InvId}
ListInvalidations GET /2020-05-31/distribution/{Id}/invalidation

Cache Policies

Operation Method Path
CreateCachePolicy POST /2020-05-31/cache-policy
GetCachePolicy GET /2020-05-31/cache-policy/{Id}
GetCachePolicyConfig GET /2020-05-31/cache-policy/{Id}/config
UpdateCachePolicy PUT /2020-05-31/cache-policy/{Id}
DeleteCachePolicy DELETE /2020-05-31/cache-policy/{Id}
ListCachePolicies GET /2020-05-31/cache-policy

Origin Request Policies

Operation Method Path
CreateOriginRequestPolicy POST /2020-05-31/origin-request-policy
GetOriginRequestPolicy GET /2020-05-31/origin-request-policy/{Id}
GetOriginRequestPolicyConfig GET /2020-05-31/origin-request-policy/{Id}/config
UpdateOriginRequestPolicy PUT /2020-05-31/origin-request-policy/{Id}
DeleteOriginRequestPolicy DELETE /2020-05-31/origin-request-policy/{Id}
ListOriginRequestPolicies GET /2020-05-31/origin-request-policy

Response Headers Policies

Operation Method Path
CreateResponseHeadersPolicy POST /2020-05-31/response-headers-policy
GetResponseHeadersPolicy GET /2020-05-31/response-headers-policy/{Id}
GetResponseHeadersPolicyConfig GET /2020-05-31/response-headers-policy/{Id}/config
UpdateResponseHeadersPolicy PUT /2020-05-31/response-headers-policy/{Id}
DeleteResponseHeadersPolicy DELETE /2020-05-31/response-headers-policy/{Id}
ListResponseHeadersPolicies GET /2020-05-31/response-headers-policy

Origin Access Control (OAC)

Operation Method Path
CreateOriginAccessControl POST /2020-05-31/origin-access-control
GetOriginAccessControl GET /2020-05-31/origin-access-control/{Id}
GetOriginAccessControlConfig GET /2020-05-31/origin-access-control/{Id}/config
UpdateOriginAccessControl PUT /2020-05-31/origin-access-control/{Id}/config
DeleteOriginAccessControl DELETE /2020-05-31/origin-access-control/{Id}
ListOriginAccessControls GET /2020-05-31/origin-access-control

UpdateOriginAccessControl accepts the current If-Match ETag and a complete configuration. With IAM enforcement enabled, its permission can be scoped to the selected origin access control ARN.

Origin Access Identity (OAI — legacy)

Operation Method Path
CreateCloudFrontOriginAccessIdentity POST /2020-05-31/origin-access-identity/cloudfront
GetCloudFrontOriginAccessIdentity GET /2020-05-31/origin-access-identity/cloudfront/{Id}
GetCloudFrontOriginAccessIdentityConfig GET /2020-05-31/origin-access-identity/cloudfront/{Id}/config
UpdateCloudFrontOriginAccessIdentity PUT /2020-05-31/origin-access-identity/cloudfront/{Id}/config
DeleteCloudFrontOriginAccessIdentity DELETE /2020-05-31/origin-access-identity/cloudfront/{Id}
ListCloudFrontOriginAccessIdentities GET /2020-05-31/origin-access-identity/cloudfront

CloudFront Functions

Operation Method Path
CreateFunction POST /2020-05-31/function
GetFunction GET /2020-05-31/function/{Name}
DescribeFunction GET /2020-05-31/function/{Name}/describe
UpdateFunction PUT /2020-05-31/function/{Name}
PublishFunction POST /2020-05-31/function/{Name}/publish
DeleteFunction DELETE /2020-05-31/function/{Name}
ListFunctions GET /2020-05-31/function

Key Value Stores

Control plane, served with the rest of CloudFront:

Operation Method Path
CreateKeyValueStore POST /2020-05-31/key-value-store
DescribeKeyValueStore GET /2020-05-31/key-value-store/{Name}
ListKeyValueStores GET /2020-05-31/key-value-store
UpdateKeyValueStore PUT /2020-05-31/key-value-store/{Name}
DeleteKeyValueStore DELETE /2020-05-31/key-value-store/{Name}

The keys of a store are read and written through the separate cloudfront-keyvaluestore data plane (REST JSON, signing name cloudfront-keyvaluestore). It names the store by its ARN, percent-encoded in the path:

Operation Method Path
DescribeKeyValueStore GET /key-value-stores/{KvsARN}
ListKeys GET /key-value-stores/{KvsARN}/keys
UpdateKeys POST /key-value-stores/{KvsARN}/keys
GetKey GET /key-value-stores/{KvsARN}/keys/{Key}
PutKey PUT /key-value-stores/{KvsARN}/keys/{Key}
DeleteKey DELETE /key-value-stores/{KvsARN}/keys/{Key}

Public Keys and Key Groups

Operation Method Path
CreatePublicKey POST /2020-05-31/public-key
GetPublicKey GET /2020-05-31/public-key/{Id}
GetPublicKeyConfig GET /2020-05-31/public-key/{Id}/config
UpdatePublicKey PUT /2020-05-31/public-key/{Id}/config
DeletePublicKey DELETE /2020-05-31/public-key/{Id}
ListPublicKeys GET /2020-05-31/public-key
CreateKeyGroup POST /2020-05-31/key-group
GetKeyGroup GET /2020-05-31/key-group/{Id}
GetKeyGroupConfig GET /2020-05-31/key-group/{Id}/config
UpdateKeyGroup PUT /2020-05-31/key-group/{Id}
DeleteKeyGroup DELETE /2020-05-31/key-group/{Id}
ListKeyGroups GET /2020-05-31/key-group

Stored configurations

These operations store what they are given and return it, so code that manages these resources works, but Floci does not act on them: a continuous deployment policy never diverts a primary distribution's requests to its staging distribution, no real-time log or monitoring-subscription metric is delivered, no field is encrypted, and a streaming distribution serves no RTMP. A staging distribution made by CopyDistribution still answers on its own domain name, as any enabled distribution does.

Staging distributions and continuous deployment

Operation Method Path
CopyDistribution POST /2020-05-31/distribution/{PrimaryDistributionId}/copy
CreateContinuousDeploymentPolicy POST /2020-05-31/continuous-deployment-policy
GetContinuousDeploymentPolicy GET /2020-05-31/continuous-deployment-policy/{Id}
UpdateContinuousDeploymentPolicy PUT /2020-05-31/continuous-deployment-policy/{Id}
DeleteContinuousDeploymentPolicy DELETE /2020-05-31/continuous-deployment-policy/{Id}
ListContinuousDeploymentPolicies GET /2020-05-31/continuous-deployment-policy

Real-time log configs

Operation Method Path
CreateRealtimeLogConfig POST /2020-05-31/realtime-log-config
GetRealtimeLogConfig POST /2020-05-31/get-realtime-log-config
UpdateRealtimeLogConfig PUT /2020-05-31/realtime-log-config
DeleteRealtimeLogConfig POST /2020-05-31/delete-realtime-log-config
ListRealtimeLogConfigs GET /2020-05-31/realtime-log-config

Field-level encryption

Operation Method Path
CreateFieldLevelEncryptionConfig POST /2020-05-31/field-level-encryption
GetFieldLevelEncryptionConfig GET /2020-05-31/field-level-encryption/{Id}/config
UpdateFieldLevelEncryptionConfig PUT /2020-05-31/field-level-encryption/{Id}/config
DeleteFieldLevelEncryptionConfig DELETE /2020-05-31/field-level-encryption/{Id}
ListFieldLevelEncryptionConfigs GET /2020-05-31/field-level-encryption
CreateFieldLevelEncryptionProfile POST /2020-05-31/field-level-encryption-profile
GetFieldLevelEncryptionProfile GET /2020-05-31/field-level-encryption-profile/{Id}
UpdateFieldLevelEncryptionProfile PUT /2020-05-31/field-level-encryption-profile/{Id}/config
DeleteFieldLevelEncryptionProfile DELETE /2020-05-31/field-level-encryption-profile/{Id}
ListFieldLevelEncryptionProfiles GET /2020-05-31/field-level-encryption-profile

Monitoring subscriptions

Operation Method Path
CreateMonitoringSubscription POST /2020-05-31/distributions/{DistributionId}/monitoring-subscription
GetMonitoringSubscription GET /2020-05-31/distributions/{DistributionId}/monitoring-subscription
DeleteMonitoringSubscription DELETE /2020-05-31/distributions/{DistributionId}/monitoring-subscription

Streaming distributions

Operation Method Path
CreateStreamingDistribution POST /2020-05-31/streaming-distribution
GetStreamingDistribution GET /2020-05-31/streaming-distribution/{Id}
GetStreamingDistributionConfig GET /2020-05-31/streaming-distribution/{Id}/config
UpdateStreamingDistribution PUT /2020-05-31/streaming-distribution/{Id}/config
DeleteStreamingDistribution DELETE /2020-05-31/streaming-distribution/{Id}

Tagging

Operation Method Path
ListTagsForResource GET /2020-05-31/tagging?Resource={arn}
TagResource POST /2020-05-31/tagging?Operation=Tag&Resource={arn}
UntagResource POST /2020-05-31/tagging?Operation=Untag&Resource={arn}

Behavior

  • All distributions are immediately set to Deployed state (no async InProgress delay).
  • Distribution IDs are 14 uppercase alphanumeric characters starting with E (e.g. E1Z2X3C4V5B6N7).
  • Distribution domain names follow the pattern {id}.cloudfront.net, with the id lower-cased as AWS writes it in a host name.
  • Public key IDs are K followed by 13 uppercase alphanumeric characters (e.g. K2JCJMDEHXQW5F), the value a signed URL carries as Key-Pair-Id. Key group, cache policy, origin request policy and response headers policy IDs are UUIDs, as they are on AWS.
  • ARNs are global — no region segment: arn:aws:cloudfront::{accountId}:distribution/{id}.
  • Invalidations are immediately marked Completed.
  • DeleteDistribution returns DistributionNotDisabled (409) if Enabled is true in the config.
  • All mutating operations (PUT, DELETE) require an If-Match header containing the current ETag. Response headers policies, public keys, and key groups distinguish a missing header (InvalidIfMatchVersion, 400) from a stale ETag (PreconditionFailed, 412). Key-value-store control-plane updates and deletes also return PreconditionFailed (412) for stale UUID versions issued by Floci; missing or malformed versions return InvalidIfMatchVersion (400). Other CloudFront resources currently return InvalidIfMatchVersion (400) for either case.
  • All GET and POST (create) responses include an ETag response header.
  • List operations emit the payload root declared by the CloudFront REST XML model (for example, ListDistributions returns <DistributionList>), with list contents represented by <Quantity>N</Quantity><Items>...</Items>.
  • OAI CallerReference uniqueness is enforced — duplicate CallerReference values return CloudFrontOriginAccessIdentityAlreadyExists (409).
  • CNAME aliases are globally unique. AssociateAlias atomically transfers an alias from its current owner to the target distribution. Exact aliases take precedence over the most-specific matching wildcard alias.
  • Viewer requests addressed to an enabled distribution's generated domain or alias are routed to the matching S3 or custom origin when the matched cache behavior's AllowedMethods includes the method; any other method returns 403 Invalid method.. A behavior without AllowedMethods allows GET and HEAD. Origin forwarding preserves the raw path, including %25 for a literal percent sign, on generated domains and aliases. Custom-origin redirects are not followed.
  • POST, PUT, PATCH and DELETE are forwarded to custom origins with the viewer request body and its Content-Type. The body is streamed to the origin with the viewer's Content-Length, or chunked when the viewer sent it chunked or, as HTTP/2 allows, with no length, so it is never held in memory. Their responses are never cached, as on AWS. Signed URL and signed cookie enforcement applies to them like any other method. Request bodies are bounded by the emulator-wide floci.protocols.max-request-size limit (FLOCI_PROTOCOLS_MAX_REQUEST_SIZE, 2048 MB by default); CloudFront accepts up to 64 GB, so raise it for larger uploads.
  • Every distribution is also served as {id}.cloudfront.{host} for each endpoint host Floci resolves: localhost, localhost.floci.io, localhost.localstack.cloud, FLOCI_HOSTNAME and every FLOCI_DNS_EXTRA_SUFFIXES entry. {id}.cloudfront.localhost.floci.io and {id}.cloudfront.localhost reach loopback with no host-file edit and are covered by the generated HTTPS certificate, so a signed URL for either can be downloaded over https://. See Downloading over HTTPS.
  • Origin custom headers are persisted through the CloudFront API and CloudFormation. They replace every same-named forwarded viewer header on custom-origin requests. For in-process S3 origins, a configured Origin header is used for S3 CORS evaluation. AWS-prohibited names, malformed values, inconsistent quantities, duplicates, and quota violations are rejected with modeled CloudFront errors when the distribution is created or updated.
  • Cache behaviors with enabled TrustedKeyGroups require a valid CloudFront signed URL or signed cookie before the origin is contacted. Signed URL parameters take precedence over signed cookies. Canned and custom policies support SHA-1 or SHA-256 signatures with RSA-2048 or ECDSA P-256 public keys. Custom policies enforce resource wildcards, expiration, optional activation time, and IPv4 CIDR restrictions. Canned resources compare literally, including query strings. Exact custom resources can include one raw query delimiter. As a conservative limitation, other custom resources containing a raw ? fail closed because the character is ambiguous with CloudFront's one-character wildcard; custom query-string wildcards are therefore not supported. Invalid or expired signatures return 403.
  • A key group must contain one to five existing public keys. Public keys that belong to a key group and key groups referenced by a cache behavior cannot be deleted until those references are removed.
  • Application query parameters are retained when constructing the resource covered by a signature. CloudFront signing parameters are excluded from that resource and are never sent to the origin.
  • S3-origin reads honor anonymous access, OAI bucket-policy or object-ACL grants, and OAC service-principal bucket-policy grants (including the distribution AWS:SourceArn) when strict S3 authentication is enabled. OAC always, never, and unsigned no-override requests follow their documented signing behavior; signed no-override viewer requests retain their authorization.
  • Requests to custom origins carry what the matched cache behavior forwards. With a cache policy, the viewer headers, cookies and query strings selected by the cache policy's ParametersInCacheKeyAndForwardedToOrigin and by the origin request policy are forwarded (the union of both). HeaderBehavior none, whitelist, allViewer, allViewerAndWhitelistCloudFront and allExcept, CookieBehavior and QueryStringBehavior none, whitelist, allExcept and all are evaluated. A cache policy that selects nothing and no origin request policy forwards no viewer headers, cookies or query strings, as on AWS, apart from the headers below that CloudFront forwards whatever the policies.
  • A cache behavior without a cache policy uses its legacy ForwardedValues: QueryString=true forwards every query string (QueryStringCacheKeys only narrows the cache key), cookies follow Forward none, whitelist (with * and ? wildcards) or all, and viewer headers are forwarded by default except Accept, Accept-Charset, Accept-Language, Authorization, Host, Referer, User-Agent and X-HTTP-Method-Override, which Headers can add back (* forwards all of them). An origin request policy needs a cache policy on AWS, so a behavior without one ignores it.
  • Whatever the policies, CloudFront sets Host to the origin's domain name unless the viewer's Host is forwarded, sends User-Agent: Amazon CloudFront unless the viewer's User-Agent is forwarded, appends the viewer address to X-Forwarded-For, adds a Via: <viewer HTTP version> <distribution domain> (CloudFront) hop and an X-Amz-Cf-Id. Authorization is always forwarded on POST, PUT, PATCH and DELETE, and on OPTIONS unless OPTIONS is a cached method; Content-Type travels with a request body; a GET or HEAD with a Range carries the viewer's Range and If-Range, since CloudFront forwards a range GET to the origin, and a HEAD can then report the range's length. Cache policy compression settings normalize Accept-Encoding to br,gzip, gzip, br or identity. Forwarded cookies are sorted by name, and cookies that are not name=value or whose name starts with $ are dropped. Hop-by-hop headers, Expect, X-Edge-*, X-Real-IP, X-Forwarded-Proto and viewer-supplied CloudFront-* headers are never forwarded.
  • Of the CloudFront request headers, CloudFront-Forwarded-Proto, CloudFront-Viewer-Address and CloudFront-Viewer-Http-Version are generated when a policy names them, or when an allExcept header behavior does not exclude them (AWS documents Managed-AllViewerExceptHostHeader as adding them). Device-type, geolocation, TLS, JA3/JA4 and header-order headers are not generated.
  • The eight AWS managed origin request policies are available by their AWS IDs through GetOriginRequestPolicy and ListOriginRequestPolicies (Type is managed or custom), and cannot be updated or deleted. The seven AWS managed cache policies with published settings (Managed-Amplify, Managed-CachingDisabled, Managed-CachingOptimized, Managed-CachingOptimizedForUncompressedObjects, Managed-Elemental-MediaPackage, Managed-UseOriginCacheControlHeaders and Managed-UseOriginCacheControlHeaders-QueryStrings) are available by their AWS IDs through GetCachePolicy, GetCachePolicyConfig and ListCachePolicies (Type is managed or custom), and cannot be updated or deleted. A behavior that references one forwards what its settings select. The four Amplify-only managed cache policies (Amplify-Default, Amplify-DefaultNoCookies, Amplify-ImageOptimization and Amplify-StaticContent) are not modeled: a behavior that references one forwards nothing.
  • In-process S3 origins do not apply forwarding settings: viewer query strings, cookies and headers do not change the S3 read, apart from the viewer's Range and If-Range on a GET or HEAD.
  • Origin responses are streamed to the viewer, from in-process S3 origins and custom origins alike, so a large object is never held in memory. A custom origin's Content-Length is passed on, and a response it sends chunked stays chunked. Floci does not cache, so it serves objects larger than 50 GB the way CloudFront does with caching disabled; with caching enabled, CloudFront refuses them.
  • WebSocket connections to custom origins are tunneled on every distribution, with no setting, as on AWS. An HTTP/1.1 GET with Upgrade: websocket and Connection: Upgrade goes to the origin the matched behavior selects with its Upgrade and Connection fields, and once the origin answers 101 Switching Protocols the viewer and origin connections are joined. Any other origin answer is relayed as an ordinary response, without custom error responses or a response headers policy, within the origin's response and response completion timeouts. The Sec-WebSocket-* fields follow the behavior's forwarding settings as any other header does, so the behavior must forward all viewer headers (the AllViewer origin request policy, or legacy cache settings) or at least Sec-WebSocket-Key and Sec-WebSocket-Version. A WebSocket handshake to an S3 origin is served as an ordinary GET.
  • Range GETs: an S3 origin serves the one byte range a viewer's Range asks for as 206 with its Content-Range, and answers 416 when the range starts past the end of the object. Any other Range gets the whole object: one CloudFront does not accept (ranges out of order or overlapping, or a negative value), several ranges, which S3 does not serve in one request, or a last byte before the first, as does a Range whose If-Range no longer describes the object, which S3 answers with the whole object. A HEAD is answered as S3's HeadObject answers a Range: a satisfiable range changes only its Content-Length, and one past the end gets 416. A custom origin gets the viewer's Range and If-Range on every GET or HEAD with a Range, whatever the forwarding settings, and its answer (206, the whole object, or 416) is passed on. Floci does not cache, so unlike CloudFront it cannot serve a later range request from an object the origin sent whole. A custom error page is served whole, whatever the Range of the request it replaces.
  • Origin Set-Cookie headers always reach the viewer. With legacy Forward=none, AWS strips them from the response; Floci does not.
  • Custom-origin requests honor the origin's connection settings. Origin.ConnectionAttempts (1 to 3, default 3) is how many times CloudFront tries to reach the origin, and Origin.ConnectionTimeout (1 to 10 seconds, default 10) how long it waits for the connection. CustomOriginConfig.OriginReadTimeout (1 to 120 seconds, default 30) bounds the wait for the origin's response, and a read timeout on a GET or HEAD is retried up to the connection attempts, as CloudFront does, while a POST, PUT, PATCH or DELETE is not retried. Origin.ResponseCompletionTimeout bounds the time the origin takes, connecting, answering and streaming the body included, over every attempt, and ends the connection when it expires; unset, or 0, leaves the origin as long as it wants to take, and a set value must be at least the read timeout. The time a slow viewer takes to read what the origin already sent is not part of it: the origin answered in time, so the response is not expired. CustomOriginConfig.OriginKeepaliveTimeout (1 to 300 seconds, default 5) is how long CloudFront keeps a connection to the origin after the last packet of a response. An origin that does not answer in time is answered 504, "The origin didn't respond before the request expired", as on AWS.
  • Custom origins that resolve to loopback, private, link-local, carrier-grade NAT, or other non-routable addresses are rejected by default. Development-only private origins must be explicitly allowlisted by exact hostname. A refused origin is logged with the host and the setting that allows it.
  • A custom origin that names this Floci itself, as localhost, 127.0.0.1, ::1 or the configured floci.hostname, on a port Floci listens on (its own port, or floci.tls.aws-https-port with TLS on) for the protocol the request uses, is served by Floci itself, so neither DNS nor the private address check applies. This is the usual local setup for a single-page app: a path-style S3 bucket as the origin path, fronted by the distribution's custom error responses. The request reaches Floci with the origin's domain as its Host, and dot segments cannot leave the origin path. A forwarded viewer Host is a 502, since it would route the request back to the distribution. The same hosts on any other port are still refused unless allowlisted.
  • A custom origin whose domain is an execute-api endpoint ({apiId}.execute-api.{region}.amazonaws.com) of an HTTP or REST API that exists in this Floci is served by Floci itself, at the address the viewer reached, through the same host routing as a direct call. The origin path names the stage, as on AWS. Neither DNS nor the private address check applies. A forwarded viewer Host is a 502, so use an origin request policy such as Managed-AllViewerExceptHostHeader. An execute-api domain of an API that does not exist in this Floci is fetched like any other custom origin. A request that the host routing would not send to the API (a WebSocket API, a disabled endpoint, a missing stage, or a region other than the API's) is answered 404 {"message":"Not Found"} and never reaches Floci's other endpoints.
  • A custom origin whose domain is a Lambda Web Function endpoint of this Floci is served by Floci itself, at the address the viewer reached. The origin names the endpoint's domainName with or without its port, and its protocol and ports do not matter, so neither DNS nor the private address check applies. A forwarded viewer Host is a 502, as on AWS, where the endpoint's certificate does not name it. Under an always-amz-auth origin access control, Floci signs these requests for the distribution. An IamAuth endpoint then lets them through, or with IAM enforcement on evaluates the function's resource policy for cloudfront.amazonaws.com, with the distribution as aws:SourceArn and its account as aws:SourceAccount. Without one, an IamAuth endpoint answers with its 403 page. CloudFront forwards the viewer's Authorization on GET and HEAD only when the cache policy includes it. A forwarded Authorization reaches the function unless it is an AWS signature.
  • Origin access controls and distributions follow the AWS checks for Lambda origins. CloudFront tells them apart by a hostname under on.aws with its fixed labels in lowercase, and Floci also by one under its own host. A Web Function endpoint needs a lambda origin access control with always-amz-auth, signed with sigv4a for a global endpoint and sigv4 otherwise, and always-amz-auth is for Web Function origins only. A Lambda@Edge origin trigger is refused in front of an origin signed with always-amz-auth or sigv4a. The execute-api origin type is refused with AccessDenied, as AWS refuses it. A distribution has to name an origin access control that exists, and a control in use keeps its origin type, its signing protocol and whether it is always-amz-auth.
  • Response headers policies validate the AWS configuration shape and are applied after the origin response, including CORS preflight fields, origin override behavior, custom headers, security headers, allowed header removals, and sampled Server-Timing metrics. Pragma: server-timing forces those metrics for enabled policies. Distribution writes reject unknown policy IDs, and policies attached to a cache behavior cannot be deleted.
  • ViewerCertificate.IAMCertificateId must be the ServerCertificateId of an uploaded IAM server certificate: distribution create and update reject an unknown one with InvalidViewerCertificate, and DeleteServerCertificate returns DeleteConflict while a distribution references it. A blank value names no certificate, which is what a distribution on the CloudFront domain name sends. The /cloudfront upload path AWS documents for a certificate meant for CloudFront is not enforced, so a certificate uploaded anywhere serves a distribution: a deliberate divergence, with both sources and what would move it under Server Certificates in IAM.
  • ViewerCertificate.ACMCertificateArn must name an existing ACM certificate: distribution create and update reject an unknown one with InvalidViewerCertificate. ACM lists the distribution's ARN under InUseBy, and DeleteCertificate returns ResourceInUseException while a distribution references it.
  • A ViewerCertificate that names a certificate is held to the two rules its own entry states. The location is ACMCertificateArn or IAMCertificateId and "not both", and a certificate named in either one "must also specify values for MinimumProtocolVersion and SSLSupportMethod". Both refusals are InvalidViewerCertificate 400, which is Floci's reading rather than a published answer: InvalidArgument and InvalidMinimumProtocolVersion are modelled on the distribution writes as well, and no sentence says which one a caller gets, so both cases read as the certificate the request carries not being valid. The Developer Guide page that enumerates what InvalidViewerCertificate answers reaches neither case either: it names the certificate's own trust, its chain, its format and the names it covers. A member carried blank counts as no value, the way a blank location member names no certificate, and a distribution on the CloudFront domain name needs neither member. The rules are read before the certificate is looked up, so a request that breaks one is refused for the rule and not for a certificate nothing matches.
  • The viewer certificate's two protocol members are held to the values they admit and to the one pair they cannot carry together. A MinimumProtocolVersion outside SSLv3, TLSv1, TLSv1_2016, TLSv1.1_2016, TLSv1.2_2018, TLSv1.2_2019, TLSv1.2_2021, TLSv1.2_2025 and TLSv1.3_2025 is InvalidMinimumProtocolVersion 400, which is published rather than read: that code's own sentence names this case. An SSLSupportMethod outside sni-only, vip and static-ip has no code of its own and is InvalidArgument 400, what this service already answers a member outside its shape with. SSLv3 alongside sni-only is InvalidProtocolSettings 400 on CreateDistribution, CreateDistributionWithTags and CopyDistribution, whose sentence names that pair and nothing else and which is the same rule as the floor the member states for SNI, "you must specify TLSv1 or higher". UpdateDistribution has never declared that code and has declared InvalidMinimumProtocolVersion since 2015, so the update answers the pair with the code it declares, which is the one a caller's SDK can map, and keeps the pair's published sentence, so the two causes the update answers under one code stay apart. The pair is read for a distribution on a certificate of its own alone, since on the CloudFront certificate the policy is replaced and the value that would make the pair is discarded. Both enumerations are read either way.
  • A distribution on the CloudFront domain name sets CloudFrontDefaultCertificate and is told to "leave all other fields empty". The member is declared boolean, so it is held to the four forms XML gives a boolean, true, false, 1 and 0, and anything else is InvalidArgument 400. That refusal is Floci's reading: CloudFront models no error for a malformed document, and reading the member for the word true alone would let a request saying yes dodge every rule below. A certificate named beside it, in ACMCertificateArn or IAMCertificateId, contradicts the request's own claim and is InvalidViewerCertificate 400, Floci's reading again. A MinimumProtocolVersion beside it is not refused: the member's entry says CloudFront "automatically sets the security policy to TLSv1 regardless of the value that you set here", so the policy a request asks for there is replaced and the config reads back TLSv1. A distribution created with no ViewerCertificate at all reads the same way, the default certificate on TLSv1. The us-east-1 restriction AWS states for ACM certificates is not enforced: a certificate is resolved from whatever region its ARN names, as long as it exists.
  • Up to 20 custom response headers policies can be created, and one policy can be associated with up to 100 distributions.
  • The five AWS managed response headers policy IDs are available and can be selected with ListResponseHeadersPolicies?Type=managed; Type uses the AWS lowercase managed or custom values.

Key Value Stores

A key value store holds the key value pairs a CloudFront Function reads at the edge. The store is created and described through the CloudFront control plane, and its keys are managed through the cloudfront-keyvaluestore data plane, which Floci serves on the same port.

  • A store has a name (1 to 64 letters, digits, hyphens and underscores) and an ARN, arn:aws:cloudfront::<account>:key-value-store/<uuid>. Stores are READY as soon as they are created.
  • The data plane takes the store's ARN in the request path, percent-encoded. The AWS SDKs prepend the account id of that ARN to the endpoint host (000000000000.localhost.floci.io), which the embedded DNS and the generated TLS certificate already cover. The requests are signed with SigV4A; Floci reads the cloudfront-keyvaluestore signing name from its credential scope and does not verify the signature. With floci.auth.validate-signatures on, these requests are refused: signature validation does not accept SigV4A outside S3 yet, so leave it off when using the data plane.
  • With IAM enforcement on, the data plane is authorized as cloudfront-keyvaluestore:<Operation> on the store's ARN, and the control plane as cloudfront:<Operation>.
  • Keys are listed in key order, 10 per page by default and up to 50 (MaxResults).
  • Quotas: a key is at most 512 bytes, a value at most 1,024 bytes and a store at most 5 MiB, counting the UTF-8 bytes of every key and value. Exceeding the first two is a ValidationException, and exceeding the store size is a ServiceQuotaExceededException. ItemCount and TotalSizeInBytes follow the same count.
  • Every key write needs the store's current data plane ETag in If-Match, and rotates it. UpdateKeys applies its puts and deletes together (at most 50 entries and 3 MB per request), and changes nothing when any entry is invalid, including a put without a Value. A stale or missing ETag on the data plane is a ValidationException ("Pre-Condition failed during update of Key-Value-Store"). Control-plane update and delete return PreconditionFailed (412) for stale UUID versions issued by Floci, and InvalidIfMatchVersion (400) for missing or malformed versions. Rejected requests preserve the store. ETags retain Floci's existing UUID representation; this does not define an AWS version format.
  • The control plane and the data plane keep independent ETags: a comment update rotates only the control plane ETag, and a key write only the data plane ETag.
  • An account can hold at most 200 stores (EntityLimitExceeded), and a store can be associated with at most 100 functions (TooManyFunctionsAssociatedToKeyValueStore). Deleting a store also drops its tags.
  • Deleting a key that is not in the store is a ResourceNotFoundException. In UpdateKeys the delete of an absent key is skipped.
  • A function can name at most one store in FunctionConfig.KeyValueStoreAssociations, and only with the cloudfront-js-2.0 runtime. The store has to exist (EntityNotFound), and a store that a function uses cannot be deleted (CannotDeleteEntityWhileInUse).
  • Floci does not run CloudFront Functions. A function that reads the store with cf.kvs() is stored and associated, but nothing executes it, so the store is useful for testing the code that writes it.

Configuration

Property Env var Default Description
floci.services.cloudfront.enabled FLOCI_SERVICES_CLOUDFRONT_ENABLED true Enable or disable the service
floci.services.cloudfront.domain-suffix FLOCI_SERVICES_CLOUDFRONT_DOMAIN_SUFFIX unset Domain suffix for generated distribution domain names. Unset, it follows the request's partition: cloudfront.net, or cloudfront.cn in China. A configured suffix applies in every partition
floci.services.cloudfront.allowed-private-origin-hosts FLOCI_SERVICES_CLOUDFRONT_ALLOWED_PRIVATE_ORIGIN_HOSTS [] Exact custom-origin hosts permitted to resolve to private/non-routable addresses (comma-separated in the environment variable)

CLI Examples

For an executable OAC example with direct-S3 and unrelated-distribution negative checks, see Private S3 origin example.

export AWS_ENDPOINT_URL=http://localhost:4566
export AWS_DEFAULT_REGION=us-east-1
export AWS_ACCESS_KEY_ID=test
export AWS_SECRET_ACCESS_KEY=test

# Create a distribution with an S3 origin
aws cloudfront create-distribution --distribution-config '{
  "CallerReference": "ref-1",
  "Enabled": true,
  "Comment": "my distribution",
  "Origins": {
    "Quantity": 1,
    "Items": [{
      "Id": "my-origin",
      "DomainName": "mybucket.s3.amazonaws.com",
      "S3OriginConfig": {"OriginAccessIdentity": ""}
    }]
  },
  "DefaultCacheBehavior": {
    "TargetOriginId": "my-origin",
    "ViewerProtocolPolicy": "redirect-to-https",
    "CachePolicyId": "658327ea-f89d-4fab-a63d-7e88639e58f6",
    "AllowedMethods": {"Quantity": 2, "Items": ["GET","HEAD"]},
    "Compress": true
  }
}'

# Get a distribution
aws cloudfront get-distribution --id E1Z2X3C4V5B6N7

# List distributions
aws cloudfront list-distributions

# Create a cache invalidation
aws cloudfront create-invalidation \
  --distribution-id E1Z2X3C4V5B6N7 \
  --invalidation-batch '{
    "CallerReference": "inv-1",
    "Paths": {"Quantity": 1, "Items": ["/*"]}
  }'

# Create an OAI (Origin Access Identity)
aws cloudfront create-cloud-front-origin-access-identity \
  --cloud-front-origin-access-identity-config \
  "CallerReference=oai-1,Comment=my-oai"

# Create an OAC (Origin Access Control)
aws cloudfront create-origin-access-control \
  --origin-access-control-config '{
    "Name": "my-oac",
    "Description": "",
    "OriginAccessControlOriginType": "s3",
    "SigningBehavior": "always",
    "SigningProtocol": "sigv4"
  }'

# Create a cache policy
aws cloudfront create-cache-policy --cache-policy-config '{
  "Name": "my-cache-policy",
  "DefaultTTL": 86400,
  "MinTTL": 0,
  "MaxTTL": 31536000,
  "ParametersInCacheKeyAndForwardedToOrigin": {
    "EnableAcceptEncodingGzip": true,
    "EnableAcceptEncodingBrotli": true,
    "HeadersConfig": {"HeaderBehavior": "none"},
    "CookiesConfig": {"CookieBehavior": "none"},
    "QueryStringsConfig": {"QueryStringBehavior": "none"}
  }
}'

# Disable and delete a distribution
ETAG=$(aws cloudfront get-distribution --id E1Z2X3C4V5B6N7 \
  --query 'ETag' --output text)
aws cloudfront update-distribution --id E1Z2X3C4V5B6N7 \
  --if-match "$ETAG" \
  --distribution-config '...(config with Enabled: false)...'
ETAG=$(aws cloudfront get-distribution --id E1Z2X3C4V5B6N7 \
  --query 'ETag' --output text)
aws cloudfront delete-distribution --id E1Z2X3C4V5B6N7 --if-match "$ETAG"

Downloading over HTTPS

A distribution's own domain name ({id}.cloudfront.net by default) resolves to nothing local, so address the distribution by one of its local delivery hostnames instead. *.cloudfront.localhost.floci.io resolves to 127.0.0.1 through public DNS and works on Linux, macOS and in containers. *.cloudfront.localhost needs no DNS at all but only resolves where the runtime handles .localhost itself, which macOS and browsers do and Debian-based images do not.

Start Floci with TLS enabled and trust its CA once:

docker run -e FLOCI_TLS_ENABLED=true -p 4566:4566 floci/floci:latest
curl -s http://localhost:4566/_floci/ca.pem -o floci-root-ca.pem

Sign the URL of the hostname you download from — the port is part of what a canned policy signs — and fetch it:

HOST=e1z2x3c4v5b6n7.cloudfront.localhost.floci.io:4566

SIGNED=$(aws cloudfront sign \
  --url "https://$HOST/hello.txt" \
  --key-pair-id K2JCJMDEHXQW5F \
  --private-key file://private_key.pem \
  --date-less-than 2026-12-31T00:00:00Z)

curl --cacert floci-root-ca.pem "$SIGNED"

To drop the :4566, publish the HTTPS port Floci also binds when TLS is on (-p 443:443, see FLOCI_TLS_AWS_HTTPS_PORT) and sign https://e1z2x3c4v5b6n7.cloudfront.localhost.floci.io/hello.txt.

Set FLOCI_SERVICES_CLOUDFRONT_DOMAIN_SUFFIX=cloudfront.localhost.floci.io to have CreateDistribution return that hostname as the DomainName, so test code can sign the API response as it is.

Behind a reverse proxy

When a proxy terminates HTTPS and forwards HTTP to Floci, sign the browser-visible HTTPS URL, including its external hostname, port and path. Floci rebuilds the signed resource from the request scheme and host, so it must receive the external scheme through trusted proxy headers. A signature made for https:// does not match a resource rebuilt as http://.

For a proxy that preserves Host and sets X-Forwarded-Proto and X-Forwarded-Port, configure the Floci container with:

environment:
  QUARKUS_HTTP_PROXY_PROXY_ADDRESS_FORWARDING: "true"
  QUARKUS_HTTP_PROXY_ALLOW_X_FORWARDED: "true"
  QUARKUS_HTTP_PROXY_ALLOW_FORWARDED: "false"
  QUARKUS_HTTP_PROXY_ENABLE_FORWARDED_HOST: "true"
  QUARKUS_HTTP_PROXY_TRUSTED_PROXIES: "<proxy source IP or CIDR>"

Replace the placeholder with the proxy's source address as seen by Floci. In Docker this may be a bridge or gateway address rather than the host's loopback address. Quarkus ignores forwarded headers from peers outside QUARKUS_HTTP_PROXY_TRUSTED_PROXIES; a missing proxy address leaves Floci seeing HTTP and a valid HTTPS URL fails with Signature does not match the policy.

For example, when signing https://e1z2x3c4v5b6n7.cloudfront.localhost.floci.io:19443/hello.txt, the proxy should forward these headers to Floci:

Host: e1z2x3c4v5b6n7.cloudfront.localhost.floci.io:19443
X-Forwarded-Proto: https
X-Forwarded-Port: 19443

A non-default external port needs X-Forwarded-Port, even when the proxy preserves Host. Applying X-Forwarded-Proto resets Quarkus' port, so preserving Host alone rebuilds the URL without :19443 and fails the signature check. Alternatively, send X-Forwarded-Host with the external hostname and port; the forwarded-host setting above enables its use.

The proxy must replace client-supplied forwarded headers, and the trusted-proxy list should cover only its actual peers. See Quarkus reverse-proxy configuration for other header layouts.

With these settings a valid proxy HTTPS signed URL succeeds; missing, expired or invalid signatures must still return 403. Verify those cases through the proxy after configuring it.

Not Supported (Phase 2)

  • Continuous deployment: a policy never diverts a primary distribution's requests to its staging distribution (see Stored configurations)
  • Delivering real-time logs, and encrypting fields with field-level encryption
  • TestFunction execution (function is stored, not executed)
  • Serving RTMP for a streaming distribution (deprecated by AWS)
  • VPC origins, Anycast IP lists
  • Importing keys into a key value store from S3: CreateKeyValueStore with an ImportSource is rejected with InvalidArgument
  • Running CloudFront Functions, so the key value store can only be read and written through its API, not from a function with cf.kvs()
  • CloudFormation provisioning of AWS::CloudFront::KeyValueStore, and KeyValueStoreAssociations on AWS::CloudFront::Function
  • Publishing the additional metrics a monitoring subscription turns on
  • CloudFormation provisioning of custom AWS::CloudFront::ResponseHeadersPolicy resources (literal custom or managed policy IDs are supported on distributions)
  • Persistent edge caching and global CDN propagation
  • Forwarding POST, PUT, PATCH and DELETE to S3 origins. AWS passes them to S3, which evaluates them against the bucket policy (OAC supports PUT and DELETE); Floci's in-process S3 origin answers them with 403 Access Denied, as S3 does for a request that holds no write grant.