# CloudFront Origins for the CDK CloudFront Library
<!--BEGIN STABILITY BANNER-->---
---
<!--END STABILITY BANNER-->
This library contains convenience methods for defining origins for a CloudFront distribution. You can use this library to create origins from
S3 buckets, Elastic Load Balancing v2 load balancers, or any other domain name.
## S3 Bucket
An S3 bucket can be added as an origin. If the bucket is configured as a website endpoint, the distribution can use S3 redirects and S3 custom error
documents.
```python
my_bucket = s3.Bucket(self, "myBucket")
cloudfront.Distribution(self, "myDist",
default_behavior=cloudfront.BehaviorOptions(origin=origins.S3Origin(my_bucket))
)
```
The above will treat the bucket differently based on if `IBucket.isWebsite` is set or not. If the bucket is configured as a website, the bucket is
treated as an HTTP origin, and the built-in S3 redirects and error pages can be used. Otherwise, the bucket is handled as a bucket origin and
CloudFront's redirect and error handling will be used. In the latter case, the Origin will create an origin access identity and grant it access to the
underlying bucket. This can be used in conjunction with a bucket that is not public to require that your users access your content using CloudFront
URLs and not S3 URLs directly. Alternatively, a custom origin access identity can be passed to the S3 origin in the properties.
### Adding Custom Headers
You can configure CloudFront to add custom headers to the requests that it sends to your origin. These custom headers enable you to send and gather information from your origin that you don’t get with typical viewer requests. These headers can even be customized for each origin. CloudFront supports custom headers for both for custom and Amazon S3 origins.
```python
my_bucket = s3.Bucket(self, "myBucket")
cloudfront.Distribution(self, "myDist",
default_behavior=cloudfront.BehaviorOptions(origin=origins.S3Origin(my_bucket,
custom_headers={
"Foo": "bar"
}
))
)
```
## ELBv2 Load Balancer
An Elastic Load Balancing (ELB) v2 load balancer may be used as an origin. In order for a load balancer to serve as an origin, it must be publicly
accessible (`internetFacing` is true). Both Application and Network load balancers are supported.
```python
import aws_cdk.aws_ec2 as ec2
import aws_cdk.aws_elasticloadbalancingv2 as elbv2
# vpc: ec2.Vpc
# Create an application load balancer in a VPC. 'internetFacing' must be 'true'
# for CloudFront to access the load balancer and use it as an origin.
lb = elbv2.ApplicationLoadBalancer(self, "LB",
vpc=vpc,
internet_facing=True
)
cloudfront.Distribution(self, "myDist",
default_behavior=cloudfront.BehaviorOptions(origin=origins.LoadBalancerV2Origin(lb))
)
```
The origin can also be customized to respond on different ports, have different connection properties, etc.
```python
import aws_cdk.aws_elasticloadbalancingv2 as elbv2
# load_balancer: elbv2.ApplicationLoadBalancer
origin = origins.LoadBalancerV2Origin(load_balancer,
connection_attempts=3,
connection_timeout=Duration.seconds(5),
read_timeout=Duration.seconds(45),
keepalive_timeout=Duration.seconds(45),
protocol_policy=cloudfront.OriginProtocolPolicy.MATCH_VIEWER
)
```
Note that the `readTimeout` and `keepaliveTimeout` properties can extend their values over 60 seconds only if a limit increase request for CloudFront origin response timeout
quota has been approved in the target account; otherwise, values over 60 seconds will produce an error at deploy time. Consider that this value is
still limited to a maximum value of 180 seconds, which is a hard limit for that quota.
## From an HTTP endpoint
Origins can also be created from any other HTTP endpoint, given the domain name, and optionally, other origin properties.
```python
cloudfront.Distribution(self, "myDist",
default_behavior=cloudfront.BehaviorOptions(origin=origins.HttpOrigin("www.example.com"))
)
```
See the documentation of `@aws-cdk/aws-cloudfront` for more information.
## Failover Origins (Origin Groups)
You can set up CloudFront with origin failover for scenarios that require high availability.
To get started, you create an origin group with two origins: a primary and a secondary.
If the primary origin is unavailable, or returns specific HTTP response status codes that indicate a failure,
CloudFront automatically switches to the secondary origin.
You achieve that behavior in the CDK using the `OriginGroup` class:
```python
my_bucket = s3.Bucket(self, "myBucket")
cloudfront.Distribution(self, "myDist",
default_behavior=cloudfront.BehaviorOptions(
origin=origins.OriginGroup(
primary_origin=origins.S3Origin(my_bucket),
fallback_origin=origins.HttpOrigin("www.example.com"),
# optional, defaults to: 500, 502, 503 and 504
fallback_status_codes=[404]
)
)
)
```
## From an API Gateway REST API
Origins can be created from an API Gateway REST API. It is recommended to use a
[regional API](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-api-endpoint-types.html) in this case.
```python
# api: apigateway.RestApi
cloudfront.Distribution(self, "Distribution",
default_behavior=cloudfront.BehaviorOptions(origin=origins.RestApiOrigin(api))
)
```
The origin path will automatically be set as the stage name.
Raw data
{
"_id": null,
"home_page": "https://github.com/aws/aws-cdk",
"name": "aws-cdk.aws-cloudfront-origins",
"maintainer": "",
"docs_url": null,
"requires_python": "~=3.7",
"maintainer_email": "",
"keywords": "",
"author": "Amazon Web Services",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/58/0a/c902dc97ae710d1278b1e46bf527333cf04dbee6bb2c30ade71a623aaa0f/aws-cdk.aws-cloudfront-origins-1.203.0.tar.gz",
"platform": null,
"description": "# CloudFront Origins for the CDK CloudFront Library\n\n<!--BEGIN STABILITY BANNER-->---\n\n\n\n\n---\n<!--END STABILITY BANNER-->\n\nThis library contains convenience methods for defining origins for a CloudFront distribution. You can use this library to create origins from\nS3 buckets, Elastic Load Balancing v2 load balancers, or any other domain name.\n\n## S3 Bucket\n\nAn S3 bucket can be added as an origin. If the bucket is configured as a website endpoint, the distribution can use S3 redirects and S3 custom error\ndocuments.\n\n```python\nmy_bucket = s3.Bucket(self, \"myBucket\")\ncloudfront.Distribution(self, \"myDist\",\n default_behavior=cloudfront.BehaviorOptions(origin=origins.S3Origin(my_bucket))\n)\n```\n\nThe above will treat the bucket differently based on if `IBucket.isWebsite` is set or not. If the bucket is configured as a website, the bucket is\ntreated as an HTTP origin, and the built-in S3 redirects and error pages can be used. Otherwise, the bucket is handled as a bucket origin and\nCloudFront's redirect and error handling will be used. In the latter case, the Origin will create an origin access identity and grant it access to the\nunderlying bucket. This can be used in conjunction with a bucket that is not public to require that your users access your content using CloudFront\nURLs and not S3 URLs directly. Alternatively, a custom origin access identity can be passed to the S3 origin in the properties.\n\n### Adding Custom Headers\n\nYou can configure CloudFront to add custom headers to the requests that it sends to your origin. These custom headers enable you to send and gather information from your origin that you don\u2019t get with typical viewer requests. These headers can even be customized for each origin. CloudFront supports custom headers for both for custom and Amazon S3 origins.\n\n```python\nmy_bucket = s3.Bucket(self, \"myBucket\")\ncloudfront.Distribution(self, \"myDist\",\n default_behavior=cloudfront.BehaviorOptions(origin=origins.S3Origin(my_bucket,\n custom_headers={\n \"Foo\": \"bar\"\n }\n ))\n)\n```\n\n## ELBv2 Load Balancer\n\nAn Elastic Load Balancing (ELB) v2 load balancer may be used as an origin. In order for a load balancer to serve as an origin, it must be publicly\naccessible (`internetFacing` is true). Both Application and Network load balancers are supported.\n\n```python\nimport aws_cdk.aws_ec2 as ec2\nimport aws_cdk.aws_elasticloadbalancingv2 as elbv2\n\n# vpc: ec2.Vpc\n\n# Create an application load balancer in a VPC. 'internetFacing' must be 'true'\n# for CloudFront to access the load balancer and use it as an origin.\nlb = elbv2.ApplicationLoadBalancer(self, \"LB\",\n vpc=vpc,\n internet_facing=True\n)\ncloudfront.Distribution(self, \"myDist\",\n default_behavior=cloudfront.BehaviorOptions(origin=origins.LoadBalancerV2Origin(lb))\n)\n```\n\nThe origin can also be customized to respond on different ports, have different connection properties, etc.\n\n```python\nimport aws_cdk.aws_elasticloadbalancingv2 as elbv2\n\n# load_balancer: elbv2.ApplicationLoadBalancer\n\norigin = origins.LoadBalancerV2Origin(load_balancer,\n connection_attempts=3,\n connection_timeout=Duration.seconds(5),\n read_timeout=Duration.seconds(45),\n keepalive_timeout=Duration.seconds(45),\n protocol_policy=cloudfront.OriginProtocolPolicy.MATCH_VIEWER\n)\n```\n\nNote that the `readTimeout` and `keepaliveTimeout` properties can extend their values over 60 seconds only if a limit increase request for CloudFront origin response timeout\nquota has been approved in the target account; otherwise, values over 60 seconds will produce an error at deploy time. Consider that this value is\nstill limited to a maximum value of 180 seconds, which is a hard limit for that quota.\n\n## From an HTTP endpoint\n\nOrigins can also be created from any other HTTP endpoint, given the domain name, and optionally, other origin properties.\n\n```python\ncloudfront.Distribution(self, \"myDist\",\n default_behavior=cloudfront.BehaviorOptions(origin=origins.HttpOrigin(\"www.example.com\"))\n)\n```\n\nSee the documentation of `@aws-cdk/aws-cloudfront` for more information.\n\n## Failover Origins (Origin Groups)\n\nYou can set up CloudFront with origin failover for scenarios that require high availability.\nTo get started, you create an origin group with two origins: a primary and a secondary.\nIf the primary origin is unavailable, or returns specific HTTP response status codes that indicate a failure,\nCloudFront automatically switches to the secondary origin.\nYou achieve that behavior in the CDK using the `OriginGroup` class:\n\n```python\nmy_bucket = s3.Bucket(self, \"myBucket\")\ncloudfront.Distribution(self, \"myDist\",\n default_behavior=cloudfront.BehaviorOptions(\n origin=origins.OriginGroup(\n primary_origin=origins.S3Origin(my_bucket),\n fallback_origin=origins.HttpOrigin(\"www.example.com\"),\n # optional, defaults to: 500, 502, 503 and 504\n fallback_status_codes=[404]\n )\n )\n)\n```\n\n## From an API Gateway REST API\n\nOrigins can be created from an API Gateway REST API. It is recommended to use a\n[regional API](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-api-endpoint-types.html) in this case.\n\n```python\n# api: apigateway.RestApi\n\ncloudfront.Distribution(self, \"Distribution\",\n default_behavior=cloudfront.BehaviorOptions(origin=origins.RestApiOrigin(api))\n)\n```\n\nThe origin path will automatically be set as the stage name.\n\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "The CDK Construct Library for AWS CloudFront Origins",
"version": "1.203.0",
"project_urls": {
"Homepage": "https://github.com/aws/aws-cdk",
"Source": "https://github.com/aws/aws-cdk.git"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "40d44e5e91b9a2b2b2dc9dafe36fd7d09ec35ab49424ac6d25f97598ac51b210",
"md5": "0b76d20440fb2c4b7462a49259dc53d6",
"sha256": "a4045d549fcd053e3695601b9c7334361aaeab8a2047878f5891d220673ebb5e"
},
"downloads": -1,
"filename": "aws_cdk.aws_cloudfront_origins-1.203.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0b76d20440fb2c4b7462a49259dc53d6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.7",
"size": 52289,
"upload_time": "2023-05-31T22:53:25",
"upload_time_iso_8601": "2023-05-31T22:53:25.872844Z",
"url": "https://files.pythonhosted.org/packages/40/d4/4e5e91b9a2b2b2dc9dafe36fd7d09ec35ab49424ac6d25f97598ac51b210/aws_cdk.aws_cloudfront_origins-1.203.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "580ac902dc97ae710d1278b1e46bf527333cf04dbee6bb2c30ade71a623aaa0f",
"md5": "4ed9f9ff5778b3aa39b8d4164bcc59ff",
"sha256": "d5e12d3b4fc32a00516df7f25ac65f4ac3d52d90636a7fc06cfa50d80f4a956b"
},
"downloads": -1,
"filename": "aws-cdk.aws-cloudfront-origins-1.203.0.tar.gz",
"has_sig": false,
"md5_digest": "4ed9f9ff5778b3aa39b8d4164bcc59ff",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.7",
"size": 53581,
"upload_time": "2023-05-31T23:01:13",
"upload_time_iso_8601": "2023-05-31T23:01:13.960070Z",
"url": "https://files.pythonhosted.org/packages/58/0a/c902dc97ae710d1278b1e46bf527333cf04dbee6bb2c30ade71a623aaa0f/aws-cdk.aws-cloudfront-origins-1.203.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-31 23:01:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aws",
"github_project": "aws-cdk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "aws-cdk.aws-cloudfront-origins"
}
JSON
