# CachePolicy

A Cache Policy configuration.

Extends: Construct › Resource › CachePolicy
Implements: IResource, ICachePolicy, IEnvironmentAware, ICachePolicyRef, IConstruct, IDependable

- CloudFormation: [`AWS::CloudFront::CachePolicy`](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-cloudfront-cachepolicy.html)
- L1 type: [`CfnCachePolicy`](/cdk/api/v2/docs/aws-cdk-lib.aws_cloudfront.CfnCachePolicy.html)
- Source: [`aws-cloudfront/lib/cache-policy.ts`](https://github.com/aws/aws-cdk/blob/v2.275.0/packages/aws-cdk-lib/aws-cloudfront/lib/cache-policy.ts#L107)
- Type last changed: v2.224.0 · 13 Nov 2025

## Example

```ts
// Create the simple Origin
const myBucket = new s3.Bucket(this, 'myBucket');
const s3Origin = origins.S3BucketOrigin.withOriginAccessControl(myBucket, {
    originAccessLevels: [cloudfront.AccessLevel.READ, cloudfront.AccessLevel.LIST],
});

// Create the Distribution construct
const myMultiTenantDistribution = new cloudfront.Distribution(this, 'distribution', {
    defaultBehavior: {
        origin: s3Origin,
    },
    defaultRootObject: 'index.html', // recommended to specify
});

// Access the underlying L1 CfnDistribution to configure SaaS Manager properties which are not yet available in the L2 Distribution construct
const cfnDistribution = myMultiTenantDistribution.node.defaultChild as cloudfront.CfnDistribution;

const defaultCacheBehavior: cloudfront.CfnDistribution.DefaultCacheBehaviorProperty = {
    targetOriginId: myBucket.bucketArn,
    viewerProtocolPolicy: 'allow-all',
    compress: false,
    allowedMethods: ['GET', 'HEAD'],
    cachePolicyId: cloudfront.CachePolicy.CACHING_OPTIMIZED.cachePolicyId
};
// Create the updated distributionConfig
const distributionConfig: cloudfront.CfnDistribution.DistributionConfigProperty = {
    defaultCacheBehavior: defaultCacheBehavior,
    enabled: true,
    // the properties below are optional
    connectionMode: 'tenant-only',
    origins: [
        {
            id: myBucket.bucketArn,
            domainName: myBucket.bucketDomainName,
            s3OriginConfig: {},
            originPath: "/{{tenantName}}"
        },
    ],
    tenantConfig: {
        parameterDefinitions: [
            {
                definition: {
                    stringSchema: {
                        required: false,
                        // the properties below are optional
                        comment: 'tenantName',
                        defaultValue: 'root',
                    },
                },
                name: 'tenantName',
            },
        ],
    },
};

// Override the distribution configuration to enable multi-tenancy.
cfnDistribution.distributionConfig = distributionConfig;

// Create a distribution tenant using an existing ACM certificate
const cfnDistributionTenant = new cloudfront.CfnDistributionTenant(this, 'distribution-tenant', {
    distributionId: myMultiTenantDistribution.distributionId,
    domains: ['my-tenant.my.domain.com'],
    name: 'my-tenant',
    enabled: true,
    parameters: [ // Override the default 'tenantName' parameter (root) defined in the multi-tenant distribution.
        {
            name: 'tenantName',
            value: 'app',
        },
    ],
    customizations: {
        certificate: {
            arn: 'REPLACE_WITH_ARN', // Certificate must be in us-east-1 region and cover 'my-tenant.my.domain.com'
        },
    },
});
```

## Initializer

```ts
new CachePolicy(scope: Construct, id: string, props?: CachePolicyProps)
```

## Construct Props

- `cachePolicyName`: string — A unique name to identify the cache policy.

  **Default:** generated from the `id`

  The name must only include '-', '_', or alphanumeric characters.

- `comment`: string — A comment to describe the cache policy.

  **Default:** no comment

  The comment cannot be longer than 128 characters.

- `cookieBehavior`: [CacheCookieBehavior](/cdk/api/v2/docs/aws-cdk-lib.aws_cloudfront.CacheCookieBehavior.html) = CacheCookieBehavior.none() — Determines whether any cookies in viewer requests are included in the cache key and automatically included in requests that CloudFront sends to the origin.

- `defaultTtl`: [Duration](/cdk/api/v2/docs/aws-cdk-lib.Duration.html) — The default amount of time for objects to stay in the CloudFront cache.

  **Default:** The greater of 1 day and ``minTtl``

  Only used when the origin does not send Cache-Control or Expires headers with the object.

- `enableAcceptEncodingBrotli`: boolean = false — Whether to normalize and include the `Accept-Encoding` header in the cache key when the `Accept-Encoding` header is 'br'.

- `enableAcceptEncodingGzip`: boolean = false — Whether to normalize and include the `Accept-Encoding` header in the cache key when the `Accept-Encoding` header is 'gzip'.

- `headerBehavior`: [CacheHeaderBehavior](/cdk/api/v2/docs/aws-cdk-lib.aws_cloudfront.CacheHeaderBehavior.html) = CacheHeaderBehavior.none() — Determines whether any HTTP headers are included in the cache key and automatically included in requests that CloudFront sends to the origin.

- `maxTtl`: [Duration](/cdk/api/v2/docs/aws-cdk-lib.Duration.html) — The maximum amount of time for objects to stay in the CloudFront cache.

  **Default:** The greater of 1 year and ``defaultTtl``

  CloudFront uses this value only when the origin sends Cache-Control or Expires headers with the object.

- `minTtl`: [Duration](/cdk/api/v2/docs/aws-cdk-lib.Duration.html) = Duration.seconds(0) — The minimum amount of time for objects to stay in the CloudFront cache.

- `queryStringBehavior`: [CacheQueryStringBehavior](/cdk/api/v2/docs/aws-cdk-lib.aws_cloudfront.CacheQueryStringBehavior.html) = CacheQueryStringBehavior.none() — Determines whether any query strings are included in the cache key and automatically included in requests that CloudFront sends to the origin.

## Properties

- `AMPLIFY`: [ICachePolicy](/cdk/api/v2/docs/aws-cdk-lib.aws_cloudfront.ICachePolicy.html) (static) — This policy is designed for use with an origin that is an AWS Amplify web app.

- `cachePolicyId`: string — The ID of the cache policy.

- `cachePolicyRef`: [CachePolicyReference](/cdk/api/v2/docs/aws-cdk-lib.interfaces.aws_cloudfront.CachePolicyReference.html) — A reference to a CachePolicy resource.

- `CACHING_DISABLED`: [ICachePolicy](/cdk/api/v2/docs/aws-cdk-lib.aws_cloudfront.ICachePolicy.html) (static) — Disables caching.

  This policy is useful for dynamic content and for requests that are not cacheable.

- `CACHING_OPTIMIZED`: [ICachePolicy](/cdk/api/v2/docs/aws-cdk-lib.aws_cloudfront.ICachePolicy.html) (static) — Optimize cache efficiency by minimizing the values that CloudFront includes in the cache key.

  Query strings and cookies are not included in the cache key, and only the normalized 'Accept-Encoding' header is included.

- `CACHING_OPTIMIZED_FOR_UNCOMPRESSED_OBJECTS`: [ICachePolicy](/cdk/api/v2/docs/aws-cdk-lib.aws_cloudfront.ICachePolicy.html) (static) — Optimize cache efficiency by minimizing the values that CloudFront includes in the cache key.

  Query strings and cookies are not included in the cache key, and only the normalized 'Accept-Encoding' header is included.
  Disables cache compression.

- `ELEMENTAL_MEDIA_PACKAGE`: [ICachePolicy](/cdk/api/v2/docs/aws-cdk-lib.aws_cloudfront.ICachePolicy.html) (static) — Designed for use with an origin that is an AWS Elemental MediaPackage endpoint.

- `env`: [ResourceEnvironment](/cdk/api/v2/docs/aws-cdk-lib.interfaces.ResourceEnvironment.html) — 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.

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

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

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

- `USE_ORIGIN_CACHE_CONTROL_HEADERS`: [ICachePolicy](/cdk/api/v2/docs/aws-cdk-lib.aws_cloudfront.ICachePolicy.html) (static) — Designed for use with an origin that returns Cache-Control HTTP response headers and does not serve different content based on values present in the query string.

- `USE_ORIGIN_CACHE_CONTROL_HEADERS_QUERY_STRINGS`: [ICachePolicy](/cdk/api/v2/docs/aws-cdk-lib.aws_cloudfront.ICachePolicy.html) (static) — Designed for use with an origin that returns Cache-Control HTTP response headers and serves different content based on values present in the query string.

## Methods

- `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`).

- `fromCachePolicyId(scope: Construct, id: string, cachePolicyId: string): ICachePolicy` (static) — Imports a Cache Policy from its id.

- `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.

- `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.