Did this page help you? Yes No Tell us about it...

DistributionConfig Complex Type

Description

The DistributionConfig complex type describes a distribution's configuration information. For more information about distributions, go to Working with Distributions in the Amazon CloudFront Developer Guide.

Usage:

POST Distribution (see request parameter)
PUT Distribution Config (see request parameter)
GET Distribution (see response element)
GET Distribution Config (see response element)

Syntax

<DistributionConfig xmlns="http://cloudfront.amazonaws.com/doc/2010-11-01/">
   <S3Origin>
      <DNSName>mybucket.s3.amazonaws.com</DNSName>
      <OriginAccessIdentity>
      origin-access-identity/cloudfront/E127EXAMPLE51Z
      </OriginAccessIdentity>
   </S3Origin>   
   <CustomOrigin>
      <DNSName>www.example.com</DNSName>
      <HTTPPort>80</HTTPPort>
      <HTTPSPort>443</HTTPSPort>
      <OriginProtocolPolicy>http-only</OriginProtocolPolicy>
   </CustomOrigin>
   <CallerReference>your unique caller reference</CallerReference>
   <CNAME>mysite.example.com</CNAME>
   <Comment>My comments</Comment>
   <Enabled>true</Enabled>
   <DefaultRootObject>index.html</DefaultRootObject>
   <Logging>
      <Bucket>mylogs.s3.amazonaws.com</Bucket>
      <Prefix>myprefix/</Prefix>
   </Logging>
   <TrustedSigners>
      <Self/>
      <AwsAccountNumber>111122223333</AwsAccountNumber>
      <AwsAccountNumber>444455556666</AwsAccountNumber>
   </TrustedSigners>
   <RequiredProtocols>
      <Protocol>https</Protocol>
   </RequiredProtocols>   
</DistributionConfig>

	Use the `S3Origin` element only if you use an Amazon S3 origin for your distribution.
	Use the `CustomOrigin` element only if you use a custom origin for your distribution.

Elements

The following table describes the child elements in the DistributionConfig datatype. They're presented in the order they appear in the configuration.

Name	Description	Required
`S3Origin`	Origin information to associate with the distribution. If your distribution will use an Amazon S3 origin, then you use the `S3Origin` element. Type: Complex Default: None Constraints: You cannot use `S3Origin` and `CustomOrigin` in the same distribution. S3Origin Children: see S3Origin Child Elements	Conditional
`CustomOrigin`	Origin information to associate with the distribution. If your distribution will use a custom origin (non Amazon S3), then you use the `CustomOrigin` element. Type: Complex Default: None Constraints: You cannot use `S3Origin` and `CustomOrigin` in the same distribution. CustomOrigin Children: see CustomOrigin Child Elements	Conditional
`CallerReference`	A unique number that ensures the request can't be replayed. If the CallerReference is new (no matter the content of the `DistributionConfig` object), a new distribution is created. If the CallerReference is a value you already sent in a previous request to create a distribution, and the content of the `DistributionConfig` is identical to the original request (ignoring white space), the response includes the same information returned to the original request. If the CallerReference is a value you already sent in a previous request to create a distribution but the content of the `DistributionConfig` is different from the original request, CloudFront returns a `DistributionAlreadyExists` error. Type: String Default: None Constraints: Allowable characters are any Unicode code points that are legal in an XML 1.0 document. The UTF-8 encoding of the value must be less than 128 bytes.	Yes
`CNAME`	A CNAME alias you want to associate with this distribution. You can have up to 10 CNAME aliases per distribution. For more information, go to Using CNAMEs in the Amazon CloudFront Developer Guide. Only include a `CNAME` element if you have a CNAME to associate with the distribution. Don't include an empty `CNAME` element in the `DistributionConfig` object. If you do, CloudFront returns a `MalformedXML` error. Type: String Default: None Valid Value: The CNAME alias	No
`Comment`	Any comments you want to include about the distribution. Type: String Default: None Constraints: Maximum 128 characters	No
`Enabled`	Whether the distribution is enabled to accept end user requests for content. Type: Boolean Default: None Valid Values: `false` \| `true`	Yes
`DefaultRootObject`	Designates a default root object. Only include a `DefaultRootObject` element if you are going to assign a default root object for the distribution. Don't include an empty `DefaultRootObject` element in the DistributionConfig object. If you do, CloudFront returns a `MalformedXML` error. For more information, go to Creating a Default Root Object in the Amazon CloudFront Developer Guide. Type: String Default: None Valid Value: The name of the object, for example, `index.html` Constraints: Maximum 255 characters. The name of the object can contain any of the following characters: a through z A through Z 0 through 9 _ (underscore) - (hyphen) . (period) * (asterisk) $ (dollar sign) / (slash) ~ (tilde) " (double quote) ' (single quote) & (ampersand, passed and returned as `&`)	No
`Logging`	A complex type that controls whether access logs are written for the distribution. If you want to turn on access logs, include this element; if you want to turn off access logs, remove this element. For more information, go to Access Logs in the Amazon CloudFront Developer Guide. Type: Complex type Default: None Children: `Bucket`, `Prefix` (for descriptions, see Logging Child Elements)	No
`TrustedSigners`	A complex type that specifies any AWS accounts you want to permit to create signed URLs for private content. If you want the distribution to use signed URLs, include this element; if you want the distribution to use basic URLs, remove this element. For more information, go to Serving Private Content in the Amazon CloudFront Developer Guide. Type: Complex type Default: None Children: `Self`, `AwsAccountNumber` (for descriptions, see TrustedSigners Child Elements)	No
`RequiredProtocols`	Defines the protocols required for your distribution. Use this element to restrict access to your distribution solely to HTTPS requests. Without this element, CloudFront can use any available protocol to serve the request. For more information, go to Creating Secure HTTPS Connections in the Amazon CloudFront Developer Guide. Type: String Default: None Children: `Protocol` (for descriptions, see RequiredProtocols Child Element)	No

S3Origin Child Elements

The following table describes the child elements of the S3Origin element.

Name Description Required

Name	Description	Required
`DNSName`	The DNS name of your Amazon S3 bucket to associate with the distribution. For example: `mybucket.s3.amazonaws.com`. Type: String Default: None Constraints: The name of the Amazon S3 bucket: Must be between 3 and 63 characters long (inclusive) Must contain only lowercase characters, numbers, periods, underscores, and dashes Must not contain adjacent periods	Yes
`OriginAccessIdentity`	The CloudFront origin access identity to associate with the distribution. If you want the distribution to serve private content, include this element; if you want the distribution to serve public content, remove this element. For more information, go to Serving Private Content in the Amazon CloudFront Developer Guide. Type: String Default: None Constraints: Must be in format `origin-access-identity/cloudfront/ID`	Optional

DNSName

The DNS name of your Amazon S3 bucket to associate with the distribution. For example: mybucket.s3.amazonaws.com.

Type: String

Default: None

Constraints: The name of the Amazon S3 bucket:

Must be between 3 and 63 characters long (inclusive)
Must contain only lowercase characters, numbers, periods, underscores, and dashes
Must not contain adjacent periods

Yes

OriginAccessIdentity

The CloudFront origin access identity to associate with the distribution. If you want the distribution to serve private content, include this element; if you want the distribution to serve public content, remove this element. For more information, go to Serving Private Content in the Amazon CloudFront Developer Guide.

Type: String

Default: None

Constraints: Must be in format origin-access-identity/cloudfront/ID

Optional

CustomOrigin Child Elements

The following table describes the child elements of the CustomOrigin element.

Name	Description	Required
`DNSName`	The origin to associate with the distribution. For example: `www.example.com`. Type: String Default: None Constraints: `DNSName` must be a valid DNS name and can contain only a-z, A-Z, 0-9, dot (.), dash (-), or underscore (_) characters, up to a maximum of 128 characters.	Yes
`HTTPPort`	The HTTP port the custom origin listens on. Type: Integer Default: 80 Valid Values: 80, 443, or 1024-65535 (inclusive)	Optional
`HTTPSPort`	The HTTPS port the custom origin listens on. Type: Integer Default: 443 Valid Values: 80, 443, or 1024-65535 (inclusive)	Optional
`OriginProtocolPolicy`	The origin protocol policy to apply to your origin. If you specify `http-only`, CloudFront uses HTTP only to access the origin. If you specify `match-viewer`, CloudFront fetches from your origin using HTTP or HTTPS, based on the protocol of the viewer request. Type: `OriginProtocolPolicy` Valid Values: `http-only` \| `match-viewer` Default: none	Yes

Logging Child Elements

The following table describes the child elements of the Logging element.

Name Description Required

Name	Description	Required
`Bucket`	The Amazon S3 bucket to store the access logs in. For example: `mylogs.s3.amazonaws.com`. Type: String Default: None Constraints: Maximum 128 characters	Yes
`Prefix`	An optional string of your choice to prefix to the access log filenames for this distribution. For example: `myprefix/`. If you decide not to use a prefix, you must still include the empty `Prefix` element in the `Logging` element. Type: String Default: None Constraints: Maximum 256 characters; the string must not start with a slash ( / ).	No

Bucket

The Amazon S3 bucket to store the access logs in. For example: mylogs.s3.amazonaws.com.

Type: String

Default: None

Constraints: Maximum 128 characters

Yes

Prefix

An optional string of your choice to prefix to the access log filenames for this distribution. For example: myprefix/.

If you decide not to use a prefix, you must still include the empty Prefix element in the Logging element.

Type: String

Default: None

Constraints: Maximum 256 characters; the string must not start with a slash ( / ).

TrustedSigners Child Elements

The following table describes the child elements of the TrustedSigners element.

Name Description Required

Name	Description	Required
`Self`	Include this empty element if you want to give your own AWS account permission to create signed URLs. Type: String Default: None	No
`AwsAccountNumber`	Specifies an AWS account that can create signed URLs. Remove the dashes. You can specify up to five accounts, each with its own `AwsAccountNumber` element. Type: String Default: None	No

Self

Include this empty element if you want to give your own AWS account permission to create signed URLs.

Type: String

Default: None

AwsAccountNumber

Specifies an AWS account that can create signed URLs. Remove the dashes. You can specify up to five accounts, each with its own AwsAccountNumber element.

Type: String

Default: None

RequiredProtocols Child Element

The following table describes the child element of the RequiredProtocols element.

Name Description Required

Name	Description	Required
`Protocol`	Specifies the protocol. Type: String Default: None Valid Value: `https`	Yes

Protocol

Specifies the protocol.

Type: String

Default: None

Valid Value: https

Yes

	Caution
The only way to guarantee that your end users retrieve an object using HTTPS is never to use any other protocol to fetch the object. If you have recently changed from HTTP to HTTPS, we recommend that you clear your objects’ cache—because cached objects are protocol agnostic. That means that an edge location will return an object from the cache irrespective of whether the current request protocol matches the protocol used previously. For information about expiring cached objects see Object Expiration in the Amazon CloudFront Developer Guide.

Caution

The only way to guarantee that your end users retrieve an object using HTTPS is never to use any other protocol to fetch the object. If you have recently changed from HTTP to HTTPS, we recommend that you clear your objects’ cache—because cached objects are protocol agnostic. That means that an edge location will return an object from the cache irrespective of whether the current request protocol matches the protocol used previously. For information about expiring cached objects see Object Expiration in the Amazon CloudFront Developer Guide.

Examples

Example of a public content distribution configuration

The following example configuration is for a public content distribution with an Amazon S3 origin, no CNAME aliases, with logging turned off, and with the distribution restricted to HTTPS protocol.

<DistributionConfig xmlns="http://cloudfront.amazonaws.com/doc/2010-11-01/">
   <S3Origin>
      <DNSName>mybucket.s3.amazonaws.com</DNSName>
   </S3Origin>   
   <CallerReference>20091130090000</CallerReference>
   <Comment>My comments</Comment>
   <Enabled>true</Enabled>
   <RequiredProtocols>
      <Protocol>https</Protocol>
   </RequiredProtocols>
</DistributionConfig>

Example of a private content distribution configuration

The following example configuration is for a distribution that serves private content with signed URLs and with two CNAME aliases. The presence of the Logging element means that logging is turned on for this distribution. This distribution also has a default root object, index.html.

<DistributionConfig xmlns="http://cloudfront.amazonaws.com/doc/2010-11-01/">
   <S3Origin>
      <DNSName>mybucket.s3.amazonaws.com</DNSName>
      <OriginAccessIdentity>
      origin-access-identity/cloudfront/E74FTE3AJFJ256A
      </OriginAccessIdentity>
   </S3Origin>   
   </CustomOrigin>
   <CallerReference>20091130090000</CallerReference>
   <CNAME>beagles.com</CNAME>
   <CNAME>beagles.dogs.com</CNAME>
   <Comment>My comments</Comment>
   <Enabled>true</Enabled>
   <DefaultRootObject>index.html</DefaultRootObject>
   <Logging>
      <Bucket>mylogs.s3.amazonaws.com</Bucket>
      <Prefix/>
   </Logging>
   <TrustedSigners>
      <Self/>
      <AwsAccountNumber>111122223333</AwsAccountNumber>
      <AwsAccountNumber>444455556666</AwsAccountNumber>
   </TrustedSigners>
</DistributionConfig>

Document Conventions
Terms of Use

Did this page help you? Yes No Tell us about it...