salt.modules.boto3_route53 module

Execution module for Amazon Route53 written against Boto 3

New in version 2017.7.0.

configuration

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 at:

http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html

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

route53.keyid: GKTADJGHEIQSXMKKRBJ08H
route53.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs

A region may also be specified in the configuration:

route53.region: us-east-1

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

myprofile:
  keyid: GKTADJGHEIQSXMKKRBJ08H
  key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs
  region: us-east-1

Note that Route53 essentially ignores all (valid) settings for 'region', since there is only one Endpoint (in us-east-1 if you care) and any (valid) region setting will just send you there. It is entirely safe to set it to None as well.

depends

boto3

salt.modules.boto3_route53.associate_vpc_with_hosted_zone(HostedZoneId=None, Name=None, VPCId=None, VPCName=None, VPCRegion=None, Comment=None, region=None, key=None, keyid=None, profile=None)

Associates an Amazon VPC with a private hosted zone.

To perform the association, the VPC and the private hosted zone must already exist. You can't convert a public hosted zone into a private hosted zone. If you want to associate a VPC from one AWS account with a zone from a another, the AWS account owning the hosted zone must first submit a CreateVPCAssociationAuthorization (using create_vpc_association_authorization() or by other means, such as the AWS console). With that done, the account owning the VPC can then call associate_vpc_with_hosted_zone() to create the association.

Note that if both sides happen to be within the same account, associate_vpc_with_hosted_zone() is enough on its own, and there is no need for the CreateVPCAssociationAuthorization step.

Also note that looking up hosted zones by name (e.g. using the Name parameter) only works within a single account - if you're associating a VPC to a zone in a different account, as outlined above, you unfortunately MUST use the HostedZoneId parameter exclusively.

HostedZoneId

The unique Zone Identifier for the Hosted Zone.

Name

The domain name associated with the Hosted Zone(s).

VPCId

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

VPCName

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

VPCRegion

When working with 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. If this fails, you'll need to provide an explicit value for VPCRegion.

Comment

Any comments you want to include about the change being made.

CLI Example:

salt myminion boto3_route53.associate_vpc_with_hosted_zone                     Name=example.org. VPCName=myVPC                     VPCRegion=us-east-1 Comment="Whoo-hoo!  I added another VPC."
salt.modules.boto3_route53.aws_encode(x)

An implementation of the encoding required to support AWS's domain name rules defined here:

While AWS's documentation specifies individual ASCII characters which need to be encoded, we instead just try to force the string to one of escaped unicode or idna depending on whether there are non-ASCII characters present.

This means that we support things like ドメイン.テスト as a domain name string.

More information about IDNA encoding in python is found here:

salt.modules.boto3_route53.change_resource_record_sets(HostedZoneId=None, Name=None, PrivateZone=None, ChangeBatch=None, region=None, key=None, keyid=None, profile=None)

See the AWS Route53 API docs as well as the Boto3 documentation for all the details...

The syntax for a ChangeBatch parameter is as follows, but note that the permutations of allowed parameters and combinations thereof are quite varied, so perusal of the above linked docs is highly recommended for any non-trival configurations.

{
    "Comment": "string",
    "Changes": [
        {
            "Action": "CREATE"|"DELETE"|"UPSERT",
            "ResourceRecordSet": {
                "Name": "string",
                "Type": "SOA"|"A"|"TXT"|"NS"|"CNAME"|"MX"|"NAPTR"|"PTR"|"SRV"|"SPF"|"AAAA",
                "SetIdentifier": "string",
                "Weight": 123,
                "Region": "us-east-1"|"us-east-2"|"us-west-1"|"us-west-2"|"ca-central-1"|"eu-west-1"|"eu-west-2"|"eu-central-1"|"ap-southeast-1"|"ap-southeast-2"|"ap-northeast-1"|"ap-northeast-2"|"sa-east-1"|"cn-north-1"|"ap-south-1",
                "GeoLocation": {
                    "ContinentCode": "string",
                    "CountryCode": "string",
                    "SubdivisionCode": "string"
                },
                "Failover": "PRIMARY"|"SECONDARY",
                "TTL": 123,
                "ResourceRecords": [
                    {
                        "Value": "string"
                    },
                ],
                "AliasTarget": {
                    "HostedZoneId": "string",
                    "DNSName": "string",
                    "EvaluateTargetHealth": True|False
                },
                "HealthCheckId": "string",
                "TrafficPolicyInstanceId": "string"
            }
        },
    ]
}

CLI Example:

foo='{
       "Name": "my-cname.example.org.",
       "TTL": 600,
       "Type": "CNAME",
       "ResourceRecords": [
         {
           "Value": "my-host.example.org"
         }
       ]
     }'
foo=`echo $foo`  # Remove newlines
salt myminion boto3_route53.change_resource_record_sets DomainName=example.org.                 keyid=A1234567890ABCDEF123 key=xblahblahblah                 ChangeBatch="{'Changes': [{'Action': 'UPSERT', 'ResourceRecordSet': $foo}]}"
salt.modules.boto3_route53.create_hosted_zone(Name, VPCId=None, VPCName=None, VPCRegion=None, CallerReference=None, Comment='', PrivateZone=False, DelegationSetId=None, region=None, key=None, keyid=None, profile=None)

Create a new Route53 Hosted Zone. Returns a Python data structure with information about the newly created Hosted Zone.

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.

VPCId

When creating a private hosted zone, either the VPC ID or VPC Name to associate with is required. Exclusive with VPCName. Ignored if passed for a non-private zone.

VPCName

When creating a private hosted zone, either the VPC ID or VPC Name to associate with is required. Exclusive with VPCId. Ignored if passed for a non-private zone.

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. If this fails, you'll need to provide an explicit value for this option. Ignored if passed for a non-private 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 is a required parameter when creating new Hosted Zones. Maximum length of 128.

Comment

Any comments you want to include about the hosted zone.

PrivateZone

Boolean - Set to True if creating a private hosted zone.

DelegationSetId

If you want to associate a reusable delegation set with this hosted zone, the ID that Amazon Route 53 assigned to the reusable delegation set when you created it. Note that XXX TODO create_delegation_set() is not yet implemented, so you'd need to manually create any delegation sets before utilizing this.

region

Region endpoint to connect to.

key

AWS key to bind with.

keyid

AWS keyid to bind with.

profile

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

CLI Example:

salt myminion boto3_route53.create_hosted_zone example.org.
salt.modules.boto3_route53.delete_hosted_zone(Id, region=None, key=None, keyid=None, profile=None)

Delete a Route53 hosted zone.

CLI Example:

salt myminion boto3_route53.delete_hosted_zone Z1234567890
salt.modules.boto3_route53.delete_hosted_zone_by_domain(Name, PrivateZone=None, region=None, key=None, keyid=None, profile=None)

Delete a Route53 hosted zone by domain name, and PrivateZone status if provided.

CLI Example:

salt myminion boto3_route53.delete_hosted_zone_by_domain example.org.
salt.modules.boto3_route53.disassociate_vpc_from_hosted_zone(HostedZoneId=None, Name=None, VPCId=None, VPCName=None, VPCRegion=None, Comment=None, region=None, key=None, keyid=None, profile=None)

Disassociates an Amazon VPC from a private hosted zone.

You can't disassociate the last VPC from a private hosted zone. You also can't convert a private hosted zone into a public hosted zone.

Note that looking up hosted zones by name (e.g. using the Name parameter) only works XXX FACTCHECK within a single AWS account - if you're disassociating a VPC in one account from a hosted zone in a different account you unfortunately MUST use the HostedZoneId parameter exclusively. XXX FIXME DOCU

HostedZoneId

The unique Zone Identifier for the Hosted Zone.

Name

The domain name associated with the Hosted Zone(s).

VPCId

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

VPCName

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

VPCRegion

When working with 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. If this fails, you'll need to provide an explicit value for VPCRegion.

Comment

Any comments you want to include about the change being made.

CLI Example:

salt myminion boto3_route53.disassociate_vpc_from_hosted_zone                     Name=example.org. VPCName=myVPC                     VPCRegion=us-east-1 Comment="Whoops!  Don't wanna talk to this-here zone no more."
salt.modules.boto3_route53.find_hosted_zone(Id=None, Name=None, PrivateZone=None, region=None, key=None, keyid=None, profile=None)

Find a hosted zone with the given characteristics.

Id

The unique Zone Identifier for the Hosted Zone. Exclusive with Name.

Name

The domain name associated with the Hosted Zone. Exclusive with Id. Note this has the potential to match more then one hosted zone (e.g. a public and a private if both exist) which will raise an error unless PrivateZone has also been passed in order split the different.

PrivateZone

Boolean - Set to True if searching for a private hosted zone.

region

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.

CLI Example:

salt myminion boto3_route53.find_hosted_zone Name=salt.org.                 profile='{"region": "us-east-1", "keyid": "A12345678AB", "key": "xblahblahblah"}'
salt.modules.boto3_route53.get_hosted_zone(Id, region=None, key=None, keyid=None, profile=None)

Return detailed info about the given zone.

Id

The unique Zone Identifier for the Hosted Zone.

region

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.

CLI Example:

salt myminion boto3_route53.get_hosted_zone Z1234567690                 profile='{"region": "us-east-1", "keyid": "A12345678AB", "key": "xblahblahblah"}'
salt.modules.boto3_route53.get_hosted_zones_by_domain(Name, region=None, key=None, keyid=None, profile=None)

Find any zones with the given domain name and return detailed info about them. Note that this can return multiple Route53 zones, since a domain name can be used in both public and private zones.

Name

The domain name associated with the Hosted Zone(s).

region

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.

CLI Example:

salt myminion boto3_route53.get_hosted_zones_by_domain salt.org.                 profile='{"region": "us-east-1", "keyid": "A12345678AB", "key": "xblahblahblah"}'
salt.modules.boto3_route53.get_resource_records(HostedZoneId=None, Name=None, StartRecordName=None, StartRecordType=None, PrivateZone=None, region=None, key=None, keyid=None, profile=None)

Get all resource records from a given zone matching the provided StartRecordName (if given) or all records in the zone (if not), optionally filtered by a specific StartRecordType. This will return any and all RRs matching, regardless of their special AWS flavors (weighted, geolocation, alias, etc.) so your code should be prepared for potentially large numbers of records back from this function - for example, if you've created a complex geolocation mapping with lots of entries all over the world providing the same server name to many different regional clients.

If you want EXACTLY ONE record to operate on, you'll need to implement any logic required to pick the specific RR you care about from those returned.

Note that if you pass in Name without providing a value for PrivateZone (either True or False), CommandExecutionError can be raised in the case of both public and private zones matching the domain. XXX FIXME DOCU

CLI example:

salt myminion boto3_route53.get_records test.example.org example.org A
salt.modules.boto3_route53.list_hosted_zones(DelegationSetId=None, region=None, key=None, keyid=None, profile=None)

Return detailed info about all zones in the bound account.

DelegationSetId

If you're using reusable delegation sets and you want to list all of the hosted zones that are associated with a reusable delegation set, specify the ID of that delegation set.

region

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.

CLI Example:

salt myminion boto3_route53.describe_hosted_zones                 profile='{"region": "us-east-1", "keyid": "A12345678AB", "key": "xblahblahblah"}'
salt.modules.boto3_route53.update_hosted_zone_comment(Id=None, Name=None, Comment=None, PrivateZone=None, region=None, key=None, keyid=None, profile=None)

Update the comment on an existing Route 53 hosted zone.

Id

The unique Zone Identifier for the Hosted Zone.

Name

The domain name associated with the Hosted Zone(s).

Comment

Any comments you want to include about the hosted zone.

PrivateZone

Boolean - Set to True if changing a private hosted zone.

CLI Example:

salt myminion boto3_route53.update_hosted_zone_comment Name=example.org.                 Comment="This is an example comment for an example zone"