# Distribution

A CloudFront distribution with associated origin(s) and caching behavior(s).

Extends: Construct › Resource › Distribution
Implements: IResource, IDistribution, IEnvironmentAware, IDistributionRef, IConstruct, IDependable

- CloudFormation: [`AWS::CloudFront::Distribution`](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-cloudfront-distribution.html)
- L1 type: [`CfnDistribution`](/cdk/api/v2/docs/aws-cdk-lib.aws_cloudfront.CfnDistribution.html)
- Source: [`aws-cloudfront/lib/distribution.ts`](https://github.com/aws/aws-cdk/blob/v2.274.0/packages/aws-cdk-lib/aws-cloudfront/lib/distribution.ts#L315)
- Type last changed: v2.227.0 · 21 Nov 2025

## Example

```ts
// Creates a distribution from a Network Load Balancer
declare const vpc: ec2.Vpc;
// Create a network load balancer in a VPC. 'internetFacing' can be 'false'.
const nlb = new elbv2.NetworkLoadBalancer(this, 'NLB', {
  vpc,
  internetFacing: false,
  vpcSubnets: { subnetType: ec2.SubnetType.PRIVATE_ISOLATED },
  securityGroups: [new ec2.SecurityGroup(this, 'NLB-SG', { vpc })],
});
new cloudfront.Distribution(this, 'myDist', {
  defaultBehavior: { origin: origins.VpcOrigin.withNetworkLoadBalancer(nlb) },
});
```

## Initializer

```ts
new Distribution(scope: Construct, id: string, props: DistributionProps)
```

## Construct Props

- `additionalBehaviors`: { [key: string]: [BehaviorOptions](/cdk/api/v2/docs/aws-cdk-lib.aws_cloudfront.BehaviorOptions.html) } — Additional behaviors for the distribution, mapped by the pathPattern that specifies which requests to apply the behavior to.

  **Default:** no additional behaviors are added.

- `certificate`: [ICertificateRef](/cdk/api/v2/docs/aws-cdk-lib.interfaces.aws_certificatemanager.ICertificateRef.html) — A certificate to associate with the distribution.

  **Default:** the CloudFront wildcard certificate (*.cloudfront.net) will be used.

  The certificate must be located in N. Virginia (us-east-1).

- `comment`: string — Any comments you want to include about the distribution.

  **Default:** no comment

- `defaultBehavior`: [BehaviorOptions](/cdk/api/v2/docs/aws-cdk-lib.aws_cloudfront.BehaviorOptions.html) (required) — The default behavior for the distribution.

- `defaultRootObject`: string — The object that you want CloudFront to request from your origin (for example, index.html) when a viewer requests the root URL for your distribution. If no default object is set, the request goes to the origin's root (e.g., example.com/).

  **Default:** no default root object

- `domainNames`: string[] — Alternative domain names for this distribution.

  **Default:** The distribution will only support the default generated name (e.g., d111111abcdef8.cloudfront.net)

  If you want to use your own domain name, such as www.example.com, instead of the cloudfront.net domain name,
  you can add an alternate domain name to your distribution. If you attach a certificate to the distribution,
  you should add (at least one of) the domain names of the certificate to this list.

  When you want to move a domain name between distributions, you can associate a certificate without specifying any domain names.
  For more information, see the _Moving an alternate domain name to a different distribution_ section in the README.

- `enabled`: boolean = true — Enable or disable the distribution.

- `enableIpv6`: boolean = true — Whether CloudFront will respond to IPv6 DNS requests with an IPv6 address.

  If you specify false, CloudFront responds to IPv6 DNS requests with the DNS response code NOERROR and with no IP addresses.
  This allows viewers to submit a second request, for an IPv4 address for your distribution.

- `enableLogging`: boolean — Enable access logging for the distribution.

  **Default:** false, unless `logBucket` is specified.

- `errorResponses`: [ErrorResponse](/cdk/api/v2/docs/aws-cdk-lib.aws_cloudfront.ErrorResponse.html)[] — How CloudFront should handle requests that are not successful (e.g., PageNotFound).

  **Default:** No custom error responses.

- `geoRestriction`: [GeoRestriction](/cdk/api/v2/docs/aws-cdk-lib.aws_cloudfront.GeoRestriction.html) — Controls the countries in which your content is distributed.

  **Default:** No geographic restrictions

- `httpVersion`: [HttpVersion](/cdk/api/v2/docs/aws-cdk-lib.aws_cloudfront.HttpVersion.html) = HttpVersion.HTTP2 — The HTTP version(s) to enable on the distribution.

  For viewers and CloudFront to use HTTP/2, viewers must support TLS 1.2 or later, and must support Server Name Indication (SNI).
  For viewers and CloudFront to use HTTP/3, viewers must support TLS 1.3 and Server Name Indication (SNI).

- `logBucket`: [IBucket](/cdk/api/v2/docs/aws-cdk-lib.aws_s3.IBucket.html) — The Amazon S3 bucket to store the access logs in.

  **Default:** A bucket is created if `enableLogging` is true

  Make sure to set `objectOwnership` to `s3.ObjectOwnership.OBJECT_WRITER` in your custom bucket.

- `logFilePrefix`: string — An optional string that you want CloudFront to prefix to the access log filenames for this distribution.

  **Default:** no prefix

- `logIncludesCookies`: boolean = false — Specifies whether you want CloudFront to include cookies in access logs.

- `minimumProtocolVersion`: [SecurityPolicyProtocol](/cdk/api/v2/docs/aws-cdk-lib.aws_cloudfront.SecurityPolicyProtocol.html) — The minimum version of the SSL protocol that you want CloudFront to use for HTTPS connections.

  **Default:** SecurityPolicyProtocol.TLS_V1_2_2021 if the '@aws-cdk/aws-cloudfront:defaultSecurityPolicyTLSv1.2_2021' feature flag is set; otherwise, SecurityPolicyProtocol.TLS_V1_2_2019.

  CloudFront serves your objects only to browsers or devices that support at
  least the SSL version that you specify.

- `priceClass`: [PriceClass](/cdk/api/v2/docs/aws-cdk-lib.aws_cloudfront.PriceClass.html) = PriceClass.PRICE_CLASS_ALL — The price class that corresponds with the maximum price that you want to pay for CloudFront service.

  If you specify PriceClass_All, CloudFront responds to requests for your objects from all CloudFront edge locations.
  If you specify a price class other than PriceClass_All, CloudFront serves your objects from the CloudFront edge location
  that has the lowest latency among the edge locations in your price class.

- `publishAdditionalMetrics`: boolean = false — Whether to enable additional CloudWatch metrics.

- `sslSupportMethod`: [SSLMethod](/cdk/api/v2/docs/aws-cdk-lib.aws_cloudfront.SSLMethod.html) = SSLMethod.SNI — The SSL method CloudFront will use for your distribution.

  Server Name Indication (SNI) - is an extension to the TLS computer networking protocol by which a client indicates
  which hostname it is attempting to connect to at the start of the handshaking process. This allows a server to present
  multiple certificates on the same IP address and TCP port number and hence allows multiple secure (HTTPS) websites
  (or any other service over TLS) to be served by the same IP address without requiring all those sites to use the same certificate.

  CloudFront can use SNI to host multiple distributions on the same IP - which a large majority of clients will support.

  If your clients cannot support SNI however - CloudFront can use dedicated IPs for your distribution - but there is a prorated monthly charge for
  using this feature. By default, we use SNI - but you can optionally enable dedicated IPs (VIP).

  See the CloudFront SSL for more details about pricing : https://aws.amazon.com/cloudfront/custom-ssl-domains/

- `webAclId`: string — Unique identifier that specifies the AWS WAF web ACL to associate with this CloudFront distribution.

  **Default:** No AWS Web Application Firewall web access control list (web ACL).

  To specify a web ACL created using the latest version of AWS WAF, use the ACL ARN, for example
  `arn:aws:wafv2:us-east-1:123456789012:global/webacl/ExampleWebACL/473e64fd-f30b-4765-81a0-62ad96dd167a`.
  To specify a web ACL created using AWS WAF Classic, use the ACL ID, for example `473e64fd-f30b-4765-81a0-62ad96dd167a`.

## Properties

- `distributionArn`: string (required) — The distribution ARN for this distribution.

- `distributionDomainName`: string (required) — The domain name of the Distribution, such as d111111abcdef8.cloudfront.net.

- `distributionId`: string (required) — The distribution ID for this distribution.

- `distributionRef`: [DistributionReference](/cdk/api/v2/docs/aws-cdk-lib.interfaces.aws_cloudfront.DistributionReference.html) (required) — A reference to a Distribution resource.

- `domainName`: string (required) — The domain name of the Distribution, such as d111111abcdef8.cloudfront.net.

- `env`: [ResourceEnvironment](/cdk/api/v2/docs/aws-cdk-lib.interfaces.ResourceEnvironment.html) (required) — The environment this resource belongs to.

  For resources that are created and managed in a Stack (those created by
  creating new class instances like `new Role()`, `new Bucket()`, etc.), this
  is always the same as the environment of the stack they belong to.

  For referenced resources (those obtained from referencing methods like
  `Role.fromRoleArn()`, `Bucket.fromBucketName()`, etc.), they might be
  different than the stack they were imported into.

- `grants`: [DistributionGrants](/cdk/api/v2/docs/aws-cdk-lib.aws_cloudfront.DistributionGrants.html) (required) — Collection of grant methods for a Distribution.

- `node`: [Node](/cdk/api/v2/docs/constructs.Node.html) (required) — The tree node.

- `PROPERTY_INJECTION_ID`: string (required) (static) — Uniquely identifies this class.

- `stack`: [Stack](/cdk/api/v2/docs/aws-cdk-lib.Stack.html) (required) — The stack in which this resource is defined.

## Methods

- `addBehavior(pathPattern: string, origin: IOrigin, behaviorOptions?: AddBehaviorOptions): void` — Adds a new behavior to this distribution for the given pathPattern.

  **Parameters**

  - `pathPattern` — the path pattern (e.g., 'images/*') that specifies which requests to apply the behavior to.
  - `origin` — the origin to use for this behavior.
  - `behaviorOptions` — the options for the behavior at this path.

- `applyCrossStackReferenceStrength(strength: ReferenceStrength): void` — Override the cross-stack reference strength for this resource.

  When set, any cross-stack reference to this resource will use the specified
  mechanism instead of the global default determined by the
  `@aws-cdk/core:defaultCrossStackReferences` context key. This is useful for
  selectively weakening specific references to avoid the "deadly embrace" problem
  without changing the app-wide default.

  **Parameters**

  - `strength` — - The reference strength to use for this resource.

- `applyRemovalPolicy(policy: RemovalPolicy): void` — Apply the given removal policy to this resource.

  The Removal Policy controls what happens to this resource when it stops
  being managed by CloudFormation, either because you've removed it from the
  CDK application or because you've made a change that requires the resource
  to be replaced.

  The resource can be deleted (`RemovalPolicy.DESTROY`), or left in your AWS
  account for data recovery and cleanup later (`RemovalPolicy.RETAIN`).

- `attachWebAclId(webAclId: string): void` — Attach WAF WebACL to this CloudFront distribution.

  WebACL must be in the us-east-1 region

  **Parameters**

  - `webAclId` — The WAF WebACL to associate with this distribution.

- `fromDistributionAttributes(scope: Construct, id: string, attrs: DistributionAttributes): IDistribution` (static) — Creates a Distribution construct that represents an external (imported) distribution.

- `grant(identity: IGrantable, ...actions: string[]): Grant` — Adds an IAM policy statement associated with this distribution to an IAM principal's policy.

  [disable-awslint:no-grants]

  **Parameters**

  - `identity` — The principal.
  - `actions` — The set of actions to allow (i.e. "cloudfront:ListInvalidations").

- `grantCreateInvalidation(identity: IGrantable): Grant` — Grant to create invalidations for this bucket to an IAM principal (Role/Group/User).

  [disable-awslint:no-grants]

  **Parameters**

  - `identity` — The principal.

- `isConstruct(x: any): boolean` (static) — Checks if `x` is a construct.

  Use this method instead of `instanceof` to properly detect `Construct`
  instances, even when the construct library is symlinked.

  Explanation: in JavaScript, multiple copies of the `constructs` library on
  disk are seen as independent, completely different libraries. As a
  consequence, the class `Construct` in each copy of the `constructs` library
  is seen as a different class, and an instance of one class will not test as
  `instanceof` the other class. `npm install` will not create installations
  like this, but users may manually symlink construct libraries together or
  use a monorepo tool: in those cases, multiple copies of the `constructs`
  library can be accidentally installed, and `instanceof` will behave
  unpredictably. It is safest to avoid using `instanceof`, and using
  this type-testing method instead.

  **Parameters**

  - `x` — Any object.

  **Returns:** true if `x` is an object created from a class which extends `Construct`.

- `isOwnedResource(construct: IConstruct): boolean` (static) — Returns true if the construct was created by CDK, and false otherwise.

- `isResource(construct: IConstruct): boolean` (static) — Check whether the given construct is a Resource.

- `metric(metricName: string, props?: MetricOptions): Metric` — Return the given named metric for this Distribution.

- `metric401ErrorRate(props?: MetricOptions): Metric` — Metric for the percentage of all viewer requests for which the response's HTTP status code is 401.

  To obtain this metric, you need to set `publishAdditionalMetrics` to `true`.

- `metric403ErrorRate(props?: MetricOptions): Metric` — Metric for the percentage of all viewer requests for which the response's HTTP status code is 403.

  To obtain this metric, you need to set `publishAdditionalMetrics` to `true`.

- `metric404ErrorRate(props?: MetricOptions): Metric` — Metric for the percentage of all viewer requests for which the response's HTTP status code is 404.

  To obtain this metric, you need to set `publishAdditionalMetrics` to `true`.

- `metric4xxErrorRate(props?: MetricOptions): Metric` — Metric for the percentage of all viewer requests for which the response's HTTP status code is 4xx.

- `metric502ErrorRate(props?: MetricOptions): Metric` — Metric for the percentage of all viewer requests for which the response's HTTP status code is 502.

  To obtain this metric, you need to set `publishAdditionalMetrics` to `true`.

- `metric503ErrorRate(props?: MetricOptions): Metric` — Metric for the percentage of all viewer requests for which the response's HTTP status code is 503.

  To obtain this metric, you need to set `publishAdditionalMetrics` to `true`.

- `metric504ErrorRate(props?: MetricOptions): Metric` — Metric for the percentage of all viewer requests for which the response's HTTP status code is 504.

  To obtain this metric, you need to set `publishAdditionalMetrics` to `true`.

- `metric5xxErrorRate(props?: MetricOptions): Metric` — Metric for the percentage of all viewer requests for which the response's HTTP status code is 5xx.

- `metricBytesDownloaded(props?: MetricOptions): Metric` — Metric for the total number of bytes downloaded by viewers for GET, HEAD, and OPTIONS requests.

- `metricBytesUploaded(props?: MetricOptions): Metric` — Metric for the total number of bytes that viewers uploaded to your origin with CloudFront, using POST and PUT requests.

- `metricCacheHitRate(props?: MetricOptions): Metric` — Metric for the percentage of all cacheable requests for which CloudFront served the content from its cache.

  HTTP POST and PUT requests, and errors, are not considered cacheable requests.

  To obtain this metric, you need to set `publishAdditionalMetrics` to `true`.

- `metricOriginLatency(props?: MetricOptions): Metric` — Metric for the total time spent from when CloudFront receives a request to when it starts providing a response to the network (not the viewer), for requests that are served from the origin, not the CloudFront cache.

  This is also known as first byte latency, or time-to-first-byte.

  To obtain this metric, you need to set `publishAdditionalMetrics` to `true`.

- `metricRequests(props?: MetricOptions): Metric` — Metric for the total number of viewer requests received by CloudFront, for all HTTP methods and for both HTTP and HTTPS requests.

- `metricTotalErrorRate(props?: MetricOptions): Metric` — Metric for the percentage of all viewer requests for which the response's HTTP status code is 4xx or 5xx.

- `toString(): string` — Returns a string representation of this construct.

- `with(...mixins: IMixin[]): IConstruct` — Applies one or more mixins to this construct.

  Mixins are applied in order. The list of constructs is captured at the
  start of the call, so constructs added by a mixin will not be visited.
  Use multiple `with()` calls if subsequent mixins should apply to added
  constructs.