salt.states.boto_cloudfront

Manage CloudFront distributions

New in version 2018.3.0.

Create, update and destroy CloudFront distributions.

This module accepts explicit AWS credentials but can also utilize IAM roles assigned to the instance through Instance Profiles. Dynamic credentials are then automatically obtained from AWS API and no further configuration is necessary. More information available here.

If IAM roles are not used you need to specify them, either in a pillar file or in the minion's config file:

cloudfront.keyid: GKTADJGHEIQSXMKKRBJ08H
cloudfront.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs

It's also possible to specify key, keyid, and region via a profile, either passed in as a dict, or a string to pull from pillars or minion config:

myprofile:
    keyid: GKTADJGHEIQSXMKKRBJ08H
    key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
    region: us-east-1
aws:
    region:
        us-east-1:
            profile:
                keyid: GKTADJGHEIQSXMKKRBJ08H
                key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
                region: us-east-1
depends

boto3

salt.states.boto_cloudfront.distribution_absent(name, region=None, key=None, keyid=None, profile=None, **kwargs)

Ensure a distribution with the given Name tag does not exist.

Note that CloudFront does not allow directly deleting an enabled Distribution. If such is requested, Salt will attempt to first update the distribution's status to Disabled, and once that returns success, to then delete the resource. THIS CAN TAKE SOME TIME, so be patient :)

name (string)

Name of the state definition.

Name (string)

Name of the CloudFront distribution to be managed. If not provided, the value of name will be used as a default. The purpose of this parameter is only to resolve it to a Resource ID, so be aware that an explicit value for Id below will override any value provided, or defaulted, here.

Id (string)

The Resource ID of a CloudFront distribution to be managed.

region (string)

Region to connect to

key (string)

Secret key to use

keyid (string)

Access key to use

profile (dict or string)

Dict, or pillar key pointing to a dict, containing AWS region/key/keyid.

Example:

Ensure a distribution named my_distribution is gone:
  boto_cloudfront.distribution_absent:
  - Name: my_distribution
salt.states.boto_cloudfront.distribution_present(name, region=None, key=None, keyid=None, profile=None, **kwargs)

Ensure the given CloudFront distribution exists in the described state.

The implementation of this function, and all those following, is orthagonal to that of boto_cloudfront.present. Resources created with boto_cloudfront.present will not be correctly managed by this function, as a different method is used to store Salt's state signifier. This function and those following are a suite, designed to work together. As an extra bonus, they correctly process updates of the managed resources, so it is recommended to use them in preference to boto_cloudfront.present above.

Note that the semantics of DistributionConfig (below) are rather arcane, and vary wildly depending on whether the distribution already exists or not (e.g. is being initially created, or being updated in place). Many more details can be found here.

name (string)

Name of the state definition.

Name (string)

Name of the resource (for purposes of Salt's idempotency). If not provided, the value of name will be used.

DistributionConfig (dict)

Configuration for the distribution.

Notes:

  • The CallerReference field should NOT be provided - it will be autopopulated by Salt.

  • A large number of sub- (and sub-sub-) fields require a Quantity element, which simply COUNTS the number of items in the Items element. This is bluntly stupid, so as a convenience, Salt will traverse the provided configuration, and add (or fix) a Quantity element for any Items elements of list-type it encounters. This adds a bit of sanity to an otherwise error-prone situation. Note that for this to work, zero-length lists must be inlined as [].

  • Due to the unavailibity of a better way to store stateful idempotency information about Distributions, the Comment sub-element (as the only user-settable attribute without weird self-blocking semantics, and which is available from the core get_distribution() API call) is utilized to store the Salt state signifier, which is used to determine resource existence and state. That said, to enable some usability of this field, only the value up to the first colon character is taken as the signifier, with everything afterward free-form, and ignored (but preserved) by Salt.

Tags (dict)

Tags to associate with the distribution.

region (string)

Region to connect to.

key (string)

Secret key to use.

keyid (string)

Access key to use.

profile (dict or string)

Dict, or pillar key pointing to a dict, containing AWS region/key/keyid.

Example:

plt-dev-spaapi-cf-dist-cf_dist-present:
  boto_cloudfront.distribution_present:
  - Name: plt-dev-spaapi-cf-dist
  - DistributionConfig:
      Comment: SPA
      Logging:
        Enabled: false
        Prefix: ''
        Bucket: ''
        IncludeCookies: false
      WebACLId: ''
      Origins:
        Items:
        - S3OriginConfig:
            OriginAccessIdentity: the-SPA-OAI
          OriginPath: ''
          CustomHeaders:
            Items: []
          Id: S3-hs-backend-srpms
          DomainName: hs-backend-srpms.s3.amazonaws.com
      PriceClass: PriceClass_All
      DefaultRootObject: ''
      Enabled: true
      DefaultCacheBehavior:
        ViewerProtocolPolicy: allow-all
        TrustedSigners:
          Items: []
          Enabled: false
        SmoothStreaming: false
        TargetOriginId: S3-hs-backend-srpms
        FieldLevelEncryptionId: ''
        ForwardedValues:
          Headers:
            Items: []
          Cookies:
            Forward: none
          QueryStringCacheKeys:
            Items: []
          QueryString: false
        MaxTTL: 31536000
        LambdaFunctionAssociations:
          Items: []
        DefaultTTL: 86400
        AllowedMethods:
          CachedMethods:
            Items:
            - HEAD
            - GET
          Items:
          - HEAD
          - GET
        MinTTL: 0
        Compress: false
      IsIPV6Enabled: true
      ViewerCertificate:
        CloudFrontDefaultCertificate: true
        MinimumProtocolVersion: TLSv1
        CertificateSource: cloudfront
      Aliases:
        Items:
        - bubba-hotep.bodhi-dev.io
      HttpVersion: http2
  - Tags:
      Owner: dev_engrs
salt.states.boto_cloudfront.oai_bucket_policy_present(name, Bucket, OAI, Policy, region=None, key=None, keyid=None, profile=None)

Ensure the given policy exists on an S3 bucket, granting access for the given origin access identity to do the things specified in the policy.

name

The name of the state definition

Bucket

The S3 bucket which CloudFront needs access to. Note that this policy is exclusive - it will be the only policy definition on the bucket (and objects inside the bucket if you specify such permissions in the policy). Note that this likely SHOULD reflect the bucket mentioned in the Resource section of the Policy, but this is not enforced...

OAI

The value of Name passed to the state definition for the origin access identity which will be accessing the bucket.

Policy

The full policy document which should be set on the S3 bucket. If a Principal clause is not provided in the policy, one will be automatically added, and pointed at the correct value as dereferenced from the OAI provided above. If one IS provided, then this is not done, and you are responsible for providing the correct values.

region (string)

Region to connect to.

key (string)

Secret key to use.

keyid (string)

Access key to use.

profile (dict or string)

Dict, or pillar key pointing to a dict, containing AWS region/key/keyid.

Example:

my_oai_s3_policy:
  boto_cloudfront.oai_bucket_policy_present:
  - Bucket: the_bucket_for_my_distribution
  - OAI: the_OAI_I_just_created_and_attached_to_my_distribution
  - Policy:
      Version: 2012-10-17
      Statement:
      - Effect: Allow
        Action: s3:GetObject
        Resource: arn:aws:s3:::the_bucket_for_my_distribution/*
salt.states.boto_cloudfront.origin_access_identity_absent(name, region=None, key=None, keyid=None, profile=None, **kwargs)

Ensure a given CloudFront Origin Access Identity is absent.

name

The name of the state definition.

Name (string)

Name of the resource (for purposes of Salt's idempotency). If not provided, the value of name will be used.

Id (string)

The Resource ID of a CloudFront origin access identity to be managed.

region (string)

Region to connect to

key (string)

Secret key to use

keyid (string)

Access key to use

profile (dict or string)

Dict, or pillar key pointing to a dict, containing AWS region/key/keyid.

Example:

Ensure an origin access identity named my_OAI is gone:
  boto_cloudfront.origin_access_identity_absent:
  - Name: my_distribution
salt.states.boto_cloudfront.origin_access_identity_present(name, region=None, key=None, keyid=None, profile=None, **kwargs)

Ensure a given CloudFront Origin Access Identity exists.

Note

Due to the unavailibity of ANY other way to store stateful idempotency information about Origin Access Identities (including resource tags), the Comment attribute (as the only user-settable attribute without weird self-blocking semantics) is necessarily utilized to store the Salt state signifier, which is used to determine resource existence and state. That said, to enable SOME usability of this field, only the value up to the first colon character is taken as the signifier, while anything afterward is free-form and ignored by Salt.

name (string)

Name of the state definition.

Name (string)

Name of the resource (for purposes of Salt's idempotency). If not provided, the value of name will be used.

Comment

Free-form text description of the origin access identity.

region (string)

Region to connect to

key (string)

Secret key to use

keyid (string)

Access key to use

profile (dict or string)

Dict, or pillar key pointing to a dict, containing AWS region/key/keyid.

Example:

my_OAI:
  boto_cloudfront.origin_access_identity_present:
  - Comment: Simply ensures an OAI named my_OAI exists
salt.states.boto_cloudfront.present(name, config, tags, region=None, key=None, keyid=None, profile=None)

Ensure the CloudFront distribution is present.

name (string)

Name of the CloudFront distribution

config (dict)

Configuration for the distribution

tags (dict)

Tags to associate with the distribution

region (string)

Region to connect to

key (string)

Secret key to use

keyid (string)

Access key to use

profile (dict or string)

A dict with region, key, and keyid, or a pillar key (string) that contains such a dict.

Example:

Manage my_distribution CloudFront distribution:
    boto_cloudfront.present:
      - name: my_distribution
      - config:
          Comment: 'partial config shown, most parameters elided'
          Enabled: True
      - tags:
          testing_key: testing_value
salt.states.boto_cloudfront.route53_alias_present(name, region=None, key=None, keyid=None, profile=None, **kwargs)

Ensure a Route53 Alias exists and is pointing at the given CloudFront distribution. An A record is always created, and if IPV6 is enabled on the given distribution, an AAAA record will be created as well. Also be aware that Alias records for CloudFront distributions are only permitted in non-private zones.

name

The name of the state definition.

Distribution

The name of the CloudFront distribution. Defaults to the value of name if not provided.

HostedZoneId

Id of the Route53 hosted zone within which the records should be created.

DomainName

The domain name associated with the Hosted Zone. Exclusive with HostedZoneId.

ResourceRecordSet

A Route53 Record Set (with AliasTarget section, suitable for use as an Alias record, if non-default settings are needed on the Alias) which should be pointed at the provided CloudFront distribution. Note that this MUST correlate with the Aliases set within the DistributionConfig section of the distribution.

Some notes specifically about the AliasTarget subsection of the ResourceRecordSet:

  • If not specified, the DNSName sub-field will be populated by dereferencing Distribution above to the value of its DomainName attribute.

  • The HostedZoneId sub-field should not be provided -- it will be automatically populated with a magic AWS value.

  • The EvaluateTargetHealth can only be False on a CloudFront Alias.

  • The above items taken all together imply that, for most use-cases, the AliasTarget sub-section can be entirely omitted, as seen in the first code sample below.

Lastly, note that if you set name to the desired ResourceRecordSet Name, you can entirely omit this parameter, as shown in the second example below.

Add a Route53 Alias for my_distribution:
  boto_cloudfront.present:
  - Distribution: my_distribution
  - DomainName: saltstack.org.
  - ResourceRecordSet:
      Name: the-alias.saltstack.org.
# This is even simpler - it uses the value of `name` for ResourceRecordSet.Name
another-alias.saltstack.org.:
  boto_cloudfront.present:
  - Distribution: my_distribution
  - DomainName: saltstack.org.