class Distribution (construct)
Language | Type name |
---|---|
![]() | Amazon.CDK.AWS.CloudFront.Distribution |
![]() | github.com/aws/aws-cdk-go/awscdk/v2/awscloudfront#Distribution |
![]() | software.amazon.awscdk.services.cloudfront.Distribution |
![]() | aws_cdk.aws_cloudfront.Distribution |
![]() | aws-cdk-lib » aws_cloudfront » Distribution |
Implements
IConstruct
, IDependable
, IResource
, IDistribution
A CloudFront distribution with associated origin(s) and caching behavior(s).
Example
// Adding an existing Lambda@Edge function created in a different stack
// to a CloudFront distribution.
declare const s3Bucket: s3.Bucket;
const functionVersion = lambda.Version.fromVersionArn(this, 'Version', 'arn:aws:lambda:us-east-1:123456789012:function:functionName:1');
new cloudfront.Distribution(this, 'distro', {
defaultBehavior: {
origin: new origins.S3Origin(s3Bucket),
edgeLambdas: [
{
functionVersion,
eventType: cloudfront.LambdaEdgeEventType.VIEWER_REQUEST,
},
],
},
});
Initializer
new Distribution(scope: Construct, id: string, props: DistributionProps)
Parameters
- scope
Construct
- id
string
- props
Distribution
Props
Construct Props
Name | Type | Description |
---|---|---|
default | Behavior | The default behavior for the distribution. |
additional | { [string]: Behavior } | Additional behaviors for the distribution, mapped by the pathPattern that specifies which requests to apply the behavior to. |
certificate? | ICertificate | A certificate to associate with the distribution. |
comment? | string | Any comments you want to include about the distribution. |
default | 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/). |
domain | string[] | Alternative domain names for this distribution. |
enable | boolean | Whether CloudFront will respond to IPv6 DNS requests with an IPv6 address. |
enable | boolean | Enable access logging for the distribution. |
enabled? | boolean | Enable or disable the distribution. |
error | Error [] | How CloudFront should handle requests that are not successful (e.g., PageNotFound). |
geo | Geo | Controls the countries in which your content is distributed. |
http | Http | Specify the maximum HTTP version that you want viewers to use to communicate with CloudFront. |
log | IBucket | The Amazon S3 bucket to store the access logs in. |
log | string | An optional string that you want CloudFront to prefix to the access log filenames for this distribution. |
log | boolean | Specifies whether you want CloudFront to include cookies in access logs. |
minimum | Security | The minimum version of the SSL protocol that you want CloudFront to use for HTTPS connections. |
price | Price | The price class that corresponds with the maximum price that you want to pay for CloudFront service. |
publish | boolean | Whether to enable additional CloudWatch metrics. |
ssl | SSLMethod | The SSL method CloudFront will use for your distribution. |
web | string | Unique identifier that specifies the AWS WAF web ACL to associate with this CloudFront distribution. |
defaultBehavior
Type:
Behavior
The default behavior for the distribution.
additionalBehaviors?
Type:
{ [string]:
Behavior
}
(optional, default: no additional behaviors are added.)
Additional behaviors for the distribution, mapped by the pathPattern that specifies which requests to apply the behavior to.
certificate?
Type:
ICertificate
(optional, default: the CloudFront wildcard certificate (.cloudfront.net) will be used.)*
A certificate to associate with the distribution.
The certificate must be located in N. Virginia (us-east-1).
comment?
Type:
string
(optional, default: no comment)
Any comments you want to include about the distribution.
defaultRootObject?
Type:
string
(optional, default: no default root object)
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/).
domainNames?
Type:
string[]
(optional, default: The distribution will only support the default generated name (e.g., d111111abcdef8.cloudfront.net))
Alternative domain names for this distribution.
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.
enableIpv6?
Type:
boolean
(optional, default: 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?
Type:
boolean
(optional, default: false, unless logBucket
is specified.)
Enable access logging for the distribution.
enabled?
Type:
boolean
(optional, default: true)
Enable or disable the distribution.
errorResponses?
Type:
Error
[]
(optional, default: No custom error responses.)
How CloudFront should handle requests that are not successful (e.g., PageNotFound).
geoRestriction?
Type:
Geo
(optional, default: No geographic restrictions)
Controls the countries in which your content is distributed.
httpVersion?
Type:
Http
(optional, default: HttpVersion.HTTP2)
Specify the maximum HTTP version that you want viewers to use to communicate with CloudFront.
For viewers and CloudFront to use HTTP/2, viewers must support TLS 1.2 or later, and must support server name identification (SNI).
logBucket?
Type:
IBucket
(optional, default: A bucket is created if enableLogging
is true)
The Amazon S3 bucket to store the access logs in.
Make sure to set objectOwnership
to s3.ObjectOwnership.OBJECT_WRITER
in your custom bucket.
logFilePrefix?
Type:
string
(optional, default: no prefix)
An optional string that you want CloudFront to prefix to the access log filenames for this distribution.
logIncludesCookies?
Type:
boolean
(optional, default: false)
Specifies whether you want CloudFront to include cookies in access logs.
minimumProtocolVersion?
Type:
Security
(optional, 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.)
The minimum version of the SSL protocol that you want CloudFront to use for HTTPS connections.
CloudFront serves your objects only to browsers or devices that support at least the SSL version that you specify.
priceClass?
Type:
Price
(optional, default: 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?
Type:
boolean
(optional, default: false)
Whether to enable additional CloudWatch metrics.
sslSupportMethod?
Type:
SSLMethod
(optional, default: 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?
Type:
string
(optional, default: No AWS Web Application Firewall web access control list (web ACL).)
Unique identifier that specifies the AWS WAF web ACL to associate with this CloudFront distribution.
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
Name | Type | Description |
---|---|---|
distribution | string | The distribution ARN for this distribution. |
distribution | string | The domain name of the Distribution, such as d111111abcdef8.cloudfront.net. |
distribution | string | The distribution ID for this distribution. |
domain | string | The domain name of the Distribution, such as d111111abcdef8.cloudfront.net. |
env | Resource | The environment this resource belongs to. |
node | Node | The tree node. |
stack | Stack | The stack in which this resource is defined. |
distributionArn
Type:
string
The distribution ARN for this distribution.
distributionDomainName
Type:
string
The domain name of the Distribution, such as d111111abcdef8.cloudfront.net.
distributionId
Type:
string
The distribution ID for this distribution.
domainName
Type:
string
The domain name of the Distribution, such as d111111abcdef8.cloudfront.net.
env
Type:
Resource
The environment this resource belongs to.
For resources that are created and managed by the CDK (generally, those created by creating new class instances like Role, Bucket, etc.), this is always the same as the environment of the stack they belong to; however, for imported resources (those obtained from static methods like fromRoleArn, fromBucketName, etc.), that might be different than the stack they were imported into.
node
Type:
Node
The tree node.
stack
Type:
Stack
The stack in which this resource is defined.
Methods
Name | Description |
---|---|
add | Adds a new behavior to this distribution for the given pathPattern. |
apply | Apply the given removal policy to this resource. |
attach | Attach WAF WebACL to this CloudFront distribution. |
grant(identity, ...actions) | Adds an IAM policy statement associated with this distribution to an IAM principal's policy. |
grant | Grant to create invalidations for this bucket to an IAM principal (Role/Group/User). |
metric(metricName, props?) | Return the given named metric for this Distribution. |
metric401 | Metric for the percentage of all viewer requests for which the response's HTTP status code is 401. |
metric403 | Metric for the percentage of all viewer requests for which the response's HTTP status code is 403. |
metric404 | Metric for the percentage of all viewer requests for which the response's HTTP status code is 404. |
metric4xx | Metric for the percentage of all viewer requests for which the response's HTTP status code is 4xx. |
metric502 | Metric for the percentage of all viewer requests for which the response's HTTP status code is 502. |
metric503 | Metric for the percentage of all viewer requests for which the response's HTTP status code is 503. |
metric504 | Metric for the percentage of all viewer requests for which the response's HTTP status code is 504. |
metric5xx | Metric for the percentage of all viewer requests for which the response's HTTP status code is 5xx. |
metric | Metric for the total number of bytes downloaded by viewers for GET, HEAD, and OPTIONS requests. |
metric | Metric for the total number of bytes that viewers uploaded to your origin with CloudFront, using POST and PUT requests. |
metric | Metric for the percentage of all cacheable requests for which CloudFront served the content from its cache. |
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. |
metric | Metric for the total number of viewer requests received by CloudFront, for all HTTP methods and for both HTTP and HTTPS requests. |
metric | Metric for the percentage of all viewer requests for which the response's HTTP status code is 4xx or 5xx. |
to | Returns a string representation of this construct. |
static from | Creates a Distribution construct that represents an external (imported) distribution. |
addBehavior(pathPattern, origin, behaviorOptions?)
public addBehavior(pathPattern: string, origin: IOrigin, behaviorOptions?: AddBehaviorOptions): void
Parameters
- pathPattern
string
— the path pattern (e.g., 'images/*') that specifies which requests to apply the behavior to. - origin
IOrigin
— the origin to use for this behavior. - behaviorOptions
Add
— the options for the behavior at this path.Behavior Options
Adds a new behavior to this distribution for the given pathPattern.
applyRemovalPolicy(policy)
public applyRemovalPolicy(policy: RemovalPolicy): void
Parameters
- policy
Removal
Policy
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)
public attachWebAclId(webAclId: string): void
Parameters
- webAclId
string
— The WAF WebACL to associate with this distribution.
Attach WAF WebACL to this CloudFront distribution.
WebACL must be in the us-east-1 region
grant(identity, ...actions)
public grant(identity: IGrantable, ...actions: string[]): Grant
Parameters
- identity
IGrantable
— The principal. - actions
string
— The set of actions to allow (i.e. "cloudfront:ListInvalidations").
Returns
Adds an IAM policy statement associated with this distribution to an IAM principal's policy.
grantCreateInvalidation(identity)
public grantCreateInvalidation(identity: IGrantable): Grant
Parameters
- identity
IGrantable
— The principal.
Returns
Grant to create invalidations for this bucket to an IAM principal (Role/Group/User).
metric(metricName, props?)
public metric(metricName: string, props?: MetricOptions): Metric
Parameters
- metricName
string
- props
Metric
Options
Returns
Return the given named metric for this Distribution.
metric401ErrorRate(props?)
public metric401ErrorRate(props?: MetricOptions): Metric
Parameters
- props
Metric
Options
Returns
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?)
public metric403ErrorRate(props?: MetricOptions): Metric
Parameters
- props
Metric
Options
Returns
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?)
public metric404ErrorRate(props?: MetricOptions): Metric
Parameters
- props
Metric
Options
Returns
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?)
public metric4xxErrorRate(props?: MetricOptions): Metric
Parameters
- props
Metric
Options
Returns
Metric for the percentage of all viewer requests for which the response's HTTP status code is 4xx.
metric502ErrorRate(props?)
public metric502ErrorRate(props?: MetricOptions): Metric
Parameters
- props
Metric
Options
Returns
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?)
public metric503ErrorRate(props?: MetricOptions): Metric
Parameters
- props
Metric
Options
Returns
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?)
public metric504ErrorRate(props?: MetricOptions): Metric
Parameters
- props
Metric
Options
Returns
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?)
public metric5xxErrorRate(props?: MetricOptions): Metric
Parameters
- props
Metric
Options
Returns
Metric for the percentage of all viewer requests for which the response's HTTP status code is 5xx.
metricBytesDownloaded(props?)
public metricBytesDownloaded(props?: MetricOptions): Metric
Parameters
- props
Metric
Options
Returns
Metric for the total number of bytes downloaded by viewers for GET, HEAD, and OPTIONS requests.
metricBytesUploaded(props?)
public metricBytesUploaded(props?: MetricOptions): Metric
Parameters
- props
Metric
Options
Returns
Metric for the total number of bytes that viewers uploaded to your origin with CloudFront, using POST and PUT requests.
metricCacheHitRate(props?)
public metricCacheHitRate(props?: MetricOptions): Metric
Parameters
- props
Metric
Options
Returns
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?)
public metricOriginLatency(props?: MetricOptions): Metric
Parameters
- props
Metric
Options
Returns
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?)
public metricRequests(props?: MetricOptions): Metric
Parameters
- props
Metric
Options
Returns
Metric for the total number of viewer requests received by CloudFront, for all HTTP methods and for both HTTP and HTTPS requests.
metricTotalErrorRate(props?)
public metricTotalErrorRate(props?: MetricOptions): Metric
Parameters
- props
Metric
Options
Returns
Metric for the percentage of all viewer requests for which the response's HTTP status code is 4xx or 5xx.
toString()
public toString(): string
Returns
string
Returns a string representation of this construct.
static fromDistributionAttributes(scope, id, attrs)
public static fromDistributionAttributes(scope: Construct, id: string, attrs: DistributionAttributes): IDistribution
Parameters
- scope
Construct
- id
string
- attrs
Distribution
Attributes
Returns
Creates a Distribution construct that represents an external (imported) distribution.