salt.states.boto3_route53

Manage Route53 records with Boto 3

New in version 2017.7.0.

Create and delete Route53 records. Be aware that this interacts with Amazon's services, and so may incur charges.

This module uses boto3, which can be installed via package, or pip.

This module accepts explicit route53 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:

route53.keyid: GKTADJGHEIQSXMKKRBJ08H
route53.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs

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

myprofile:
  keyid: GKTADJGHEIQSXMKKRBJ08H
  key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
  region: us-east-1
An exciting new AWS Route 53 Hosted Zone:
  boto_route53.hosted_zone_present:
    - Name: example.com.
    - PrivateZone: true
    - VPCs:
      - VPCName: MyLittleVPC
        VPCRegion: us-east-1
      - VPCId: vpc-12345678
    - region: us-east-1
    - keyid: GKTADJGHEIQSXMKKRBJ08H
    - key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs

mycnamerecord:
  boto_route53.rr_present:
    - Name: test.example.com.
    - ResourceRecords:
      - my-elb.us-east-1.elb.amazonaws.com.
    - DomainName: example.com.
    - TTL: 60
    - Type: CNAME
    - region: us-east-1
    - keyid: GKTADJGHEIQSXMKKRBJ08H
    - key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
salt.states.boto3_route53.hosted_zone_absent(name, Name=None, PrivateZone=False, region=None, key=None, keyid=None, profile=None)

Ensure the Route53 Hostes Zone described is absent

name

The name of the state definition.

Name

The name of the domain. This should be a fully-specified domain, and should terminate with a period. If not provided, the value of name will be used.

PrivateZone

Set True if deleting a private hosted zone.

salt.states.boto3_route53.hosted_zone_present(name, Name=None, PrivateZone=False, CallerReference=None, Comment=None, VPCs=None, region=None, key=None, keyid=None, profile=None)

Ensure a hosted zone exists with the given attributes.

name

The name of the state definition.

Name

The name of the domain. This should be a fully-specified domain, and should terminate with a period. This is the name you have registered with your DNS registrar. It is also the name you will delegate from your registrar to the Amazon Route 53 delegation servers returned in response to this request. If not provided, the value of name will be used.

PrivateZone

Set True if creating a private hosted zone. If true, then 'VPCs' is also required.

Comment

Any comments you want to include about the hosted zone.

CallerReference

A unique string that identifies the request and that allows create_hosted_zone() calls to be retried without the risk of executing the operation twice. This helps ensure idempotency across state calls, but can cause issues if a zone is deleted and then an attempt is made to recreate it with the same CallerReference. If not provided, a unique UUID will be generated at each state run, which can potentially lead to duplicate zones being created if the state is run again while the previous zone creation is still in PENDING status (which can occasionally take several minutes to clear). Maximum length of 128.

VPCs

A list of dicts, each dict composed of a VPCRegion, and either a VPCId or a VPCName. Note that this param is ONLY used if PrivateZone == True

VPCId

When creating a private hosted zone, either the VPC ID or VPC Name to associate with is required. Exclusive with VPCName.

VPCName

When creating a private hosted zone, either the VPC ID or VPC Name to associate with is required. Exclusive with VPCId.

VPCRegion

When creating a private hosted zone, the region of the associated VPC is required. If not provided, an effort will be made to determine it from VPCId or VPCName, if possible. This will fail if a given VPCName exists in multiple regions visible to the bound account, in which case you'll need to provide an explicit value for VPCRegion.

salt.states.boto3_route53.rr_absent(name, HostedZoneId=None, DomainName=None, PrivateZone=False, Name=None, Type=None, SetIdentifier=None, region=None, key=None, keyid=None, profile=None)

Ensure the Route53 record is deleted.

name

The name of the state definition. This will be used for Name if the latter is not provided.

HostedZoneId

The ID of the zone to delete the record from. Exclusive with DomainName.

DomainName

The domain name of the zone to delete the record from. Exclusive with HostedZoneId.

PrivateZone

Set to True if the RR to be removed is in a private zone, False if public.

Name

Name of the resource record.

Type

The record type (A, NS, MX, TXT, etc.)

SetIdentifier

Valid for Weighted, Latency, Geolocation, and Failover resource record sets only. An identifier that differentiates among multiple resource record sets that have the same combination of DNS name and type. The value of SetIdentifier must be unique for each resource record set that has the same combination of DNS name and type. Omit SetIdentifier for any other types of record sets.

region

The region to connect to.

key

Secret key to be used.

keyid

Access key to be used.

profile

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

salt.states.boto3_route53.rr_present(name, HostedZoneId=None, DomainName=None, PrivateZone=False, Name=None, Type=None, SetIdentifier=None, Weight=None, Region=None, GeoLocation=None, Failover=None, TTL=None, ResourceRecords=None, AliasTarget=None, HealthCheckId=None, TrafficPolicyInstanceId=None, region=None, key=None, keyid=None, profile=None)

Ensure the Route53 record is present.

name

The name of the state definition. This will be used for Name if the latter is not provided.

HostedZoneId

The ID of a zone to create the record in. Exclusive with DomainName.

DomainName

The domain name of a zone to create the record in. Exclusive with HostedZoneId.

PrivateZone

Set to True if the resource record should be in a private zone, False if public.

Name

Name of the Route 53 resource record being managed.

Type

The record type (A, NS, MX, TXT, etc.)

SetIdentifier

Valid for Weighted, Latency, Geolocation, and Failover resource record sets only. An identifier that differentiates among multiple resource record sets that have the same combination of DNS name and type. The value of SetIdentifier must be unique for each resource record set that has the same combination of DNS name and type. Omit SetIdentifier for any other types of record sets.

Weight

Valid for Weighted resource record sets only. Among resource record sets that have the same combination of DNS name and type, a value that determines the proportion of DNS queries that Amazon Route 53 responds to using the current resource record set. Amazon Route 53 calculates the sum of the weights for the resource record sets that have the same combination of DNS name and type. Amazon Route 53 then responds to queries based on the ratio of a resource's weight to the total.

Note the following:

  • You must specify a value for the Weight element for every weighted resource record set.

  • You can only specify one ResourceRecord per weighted resource record set.

  • You can't create latency, failover, or geolocation resource record sets that have the same values for the Name and Type elements as weighted resource record sets.

  • You can create a maximum of 100 weighted resource record sets that have the same values for the Name and Type elements.

  • For weighted (but not weighted alias) resource record sets, if you set Weight to 0 for a resource record set, Amazon Route 53 never responds to queries with the applicable value for that resource record set. However, if you set Weight to 0 for all resource record sets that have the same combination of DNS name and type, traffic is routed to all resources with equal probability. The effect of setting Weight to 0 is different when you associate health checks with weighted resource record sets. For more information, see Options for Configuring Amazon Route 53 Active-Active and Active-Passive Failover in the Amazon Route 53 Developer Guide.

Region

Valid for Latency-based resource record sets only. The Amazon EC2 Region where the resource that is specified in this resource record set resides. The resource typically is an AWS resource, such as an EC2 instance or an ELB load balancer, and is referred to by an IP address or a DNS domain name, depending on the record type.

GeoLocation

Geo location resource record sets only. A dict that lets you control how Route 53 responds to DNS queries based on the geographic origin of the query. For example, if you want all queries from Africa to be routed to a web server with an IP address of 192.0.2.111, create a resource record set with a Type of A and a ContinentCode of AF.

ContinentCode
    The two-letter code for the continent.
    Valid values: AF | AN | AS | EU | OC | NA | SA
    Constraint: Specifying ContinentCode with either CountryCode or SubdivisionCode
                returns an InvalidInput error.
CountryCode
    The two-letter code for the country.
SubdivisionCode
    The code for the subdivision, for example, a state in the United States or a
    province in Canada.

Notes

  • Creating geolocation and geolocation alias resource record sets in private hosted zones is not supported.

  • If you create separate resource record sets for overlapping geographic regions (for example, one resource record set for a continent and one for a country on the same continent), priority goes to the smallest geographic region. This allows you to route most queries for a continent to one resource and to route queries for a country on that continent to a different resource.

  • You can't create two geolocation resource record sets that specify the same geographic location.

  • The value * in the CountryCode element matches all geographic locations that aren't specified in other geolocation resource record sets that have the same values for the Name and Type elements.

  • Geolocation works by mapping IP addresses to locations. However, some IP addresses aren't mapped to geographic locations, so even if you create geolocation resource record sets that cover all seven continents, Amazon Route 53 will receive some DNS queries from locations that it can't identify. We recommend that you create a resource record set for which the value of CountryCode is *, which handles both queries that come from locations for which you haven't created geolocation resource record sets and queries from IP addresses that aren't mapped to a location. If you don't create a * resource record set, Amazon Route 53 returns a "no answer" response for queries from those locations.

  • You can't create non-geolocation resource record sets that have the same values for the Name and Type elements as geolocation resource record sets.

TTL

The resource record cache time to live (TTL), in seconds. Note the following:

  • If you're creating an alias resource record set, omit TTL. Amazon Route 53 uses the value of TTL for the alias target.

  • If you're associating this resource record set with a health check (if you're adding a HealthCheckId element), we recommend that you specify a TTL of 60 seconds or less so clients respond quickly to changes in health status.

  • All of the resource record sets in a group of weighted, latency, geolocation, or failover resource record sets must have the same value for TTL.

  • If a group of weighted resource record sets includes one or more weighted alias resource record sets for which the alias target is an ELB load balancer, we recommend that you specify a TTL of 60 seconds for all of the non-alias weighted resource record sets that have the same name and type. Values other than 60 seconds (the TTL for load balancers) will change the effect of the values that you specify for Weight.

ResourceRecords

A list, containing one or more values for the resource record. No single value can exceed 4,000 characters. For details on how to format values for different record types, see Supported DNS Resource Record Types in the Amazon Route 53 Developer Guide.

Note: You can specify more than one value for all record types except CNAME and SOA.

It is also possible to pass "magic" strings as resource record values. This functionality can easily be extended, but for the moment supports the following:

'magic:ec2_instance_tag:some_tag_name:some_string:some_instance_attr'

This tells salt to lookup an EC2 instance with a tag 'some_tag_name' which has the value 'some_string' and substitute the 'some_instance_attr' attribute of that instance as the resource record value being evaluated.

This should work generally for any EC2 instance tags, as long as the instance attribute being fetched is available to getattr(instance, 'attribute') as seen in the code below. Anything else will most likely require this function to be extended to handle it.

The canonical use-case for this (at least at our site) is to query the Name tag (which we always populate with the host's FQDN) to lookup the public or private IPs bound to the instance, so we can then automgically create Route 53 records for them.

AliasTarget

The rules governing how to define an AliasTarget for the various supported use-cases are obtuse beyond reason and attempting to paraphrase them (or even worse, cut-and-paste them in their entirety) would be silly and counterproductive. If you need this feature, then Read The Fine Materials at the Boto 3 Route 53 page and/or the AWS Route 53 docs and suss them for yourself - I sure won't claim to understand them partcularly well.

region

The region to connect to.

key

Secret key to be used.

keyid

Access key to be used.

profile

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