Route53 / Client / create_hosted_zone

create_hosted_zone

Route53.Client.create_hosted_zone(**kwargs)

Creates a new public or private hosted zone. You create records in a public hosted zone to define how you want to route traffic on the internet for a domain, such as example.com, and its subdomains (apex.example.com, acme.example.com). You create records in a private hosted zone to define how you want to route traffic for a domain and its subdomains within one or more Amazon Virtual Private Clouds (Amazon VPCs).

Warning

You can’t convert a public hosted zone to a private hosted zone or vice versa. Instead, you must create a new hosted zone with the same name and create new resource record sets.

For more information about charges for hosted zones, see Amazon Route 53 Pricing.

Note the following:

• You can’t create a hosted zone for a top-level domain (TLD) such as .com.

• For public hosted zones, Route 53 automatically creates a default SOA record and four NS records for the zone. For more information about SOA and NS records, see NS and SOA Records that Route 53 Creates for a Hosted Zone in the Amazon Route 53 Developer Guide. If you want to use the same name servers for multiple public hosted zones, you can optionally associate a reusable delegation set with the hosted zone. See the DelegationSetId element.

• If your domain is registered with a registrar other than Route 53, you must update the name servers with your registrar to make Route 53 the DNS service for the domain. For more information, see Migrating DNS Service for an Existing Domain to Amazon Route 53 in the Amazon Route 53 Developer Guide.

When you submit a CreateHostedZone request, the initial status of the hosted zone is PENDING. For public hosted zones, this means that the NS and SOA records are not yet available on all Route 53 DNS servers. When the NS and SOA records are available, the status of the zone changes to INSYNC.

The CreateHostedZone request requires the caller to have an ec2:DescribeVpcs permission.

Note

When creating private hosted zones, the Amazon VPC must belong to the same partition where the hosted zone is created. A partition is a group of Amazon Web Services Regions. Each Amazon Web Services account is scoped to one partition.

The following are the supported partitions:

• aws - Amazon Web Services Regions

• aws-cn - China Regions

• aws-us-gov - Amazon Web Services GovCloud (US) Region

For more information, see Access Management in the Amazon Web Services General Reference.

See also: AWS API Documentation

Request Syntax

response = client.create_hosted_zone(
    Name='string',
    VPC={
        'VPCRegion': 'us-east-1'|'us-east-2'|'us-west-1'|'us-west-2'|'eu-west-1'|'eu-west-2'|'eu-west-3'|'eu-central-1'|'eu-central-2'|'ap-east-1'|'me-south-1'|'us-gov-west-1'|'us-gov-east-1'|'us-iso-east-1'|'us-iso-west-1'|'us-isob-east-1'|'me-central-1'|'ap-southeast-1'|'ap-southeast-2'|'ap-southeast-3'|'ap-south-1'|'ap-south-2'|'ap-northeast-1'|'ap-northeast-2'|'ap-northeast-3'|'eu-north-1'|'sa-east-1'|'ca-central-1'|'cn-north-1'|'af-south-1'|'eu-south-1'|'eu-south-2'|'ap-southeast-4'|'il-central-1'|'ca-west-1'|'ap-southeast-5',
        'VPCId': 'string'
    },
    CallerReference='string',
    HostedZoneConfig={
        'Comment': 'string',
        'PrivateZone': True|False
    },
    DelegationSetId='string'
)

Parameters:

• Name (string) –

  [REQUIRED]

  The name of the domain. Specify a fully qualified domain name, for example, www.example.com. The trailing dot is optional; Amazon Route 53 assumes that the domain name is fully qualified. This means that Route 53 treats www.example.com (without a trailing dot) and www.example.com. (with a trailing dot) as identical.

  If you’re creating a public hosted zone, this is the name you have registered with your DNS registrar. If your domain name is registered with a registrar other than Route 53, change the name servers for your domain to the set of NameServers that CreateHostedZone returns in DelegationSet.

• VPC (dict) –

  (Private hosted zones only) A complex type that contains information about the Amazon VPC that you’re associating with this hosted zone.

  You can specify only one Amazon VPC when you create a private hosted zone. If you are associating a VPC with a hosted zone with this request, the paramaters VPCId and VPCRegion are also required.

  To associate additional Amazon VPCs with the hosted zone, use AssociateVPCWithHostedZone after you create a hosted zone.

  • VPCRegion (string) –

    (Private hosted zones only) The region that an Amazon VPC was created in.

  • VPCId (string) –

    (Private hosted zones only) The ID of an Amazon VPC.

• CallerReference (string) –

  [REQUIRED]

  A unique string that identifies the request and that allows failed CreateHostedZone requests to be retried without the risk of executing the operation twice. You must use a unique CallerReference string every time you submit a CreateHostedZone request. CallerReference can be any unique string, for example, a date/time stamp.

• HostedZoneConfig (dict) –

  (Optional) A complex type that contains the following optional values:

  • For public and private hosted zones, an optional comment

  • For private hosted zones, an optional PrivateZone element

  If you don’t specify a comment or the PrivateZone element, omit HostedZoneConfig and the other elements.

  • Comment (string) –

    Any comments that you want to include about the hosted zone.

  • PrivateZone (boolean) –

    A value that indicates whether this is a private hosted zone.

• DelegationSetId (string) –

  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. For more information about reusable delegation sets, see CreateReusableDelegationSet.

  If you are using a reusable delegation set to create a public hosted zone for a subdomain, make sure that the parent hosted zone doesn’t use one or more of the same name servers. If you have overlapping nameservers, the operation will cause a ConflictingDomainsExist error.

Return type:

dict

Returns:

Response Syntax

{
    'HostedZone': {
        'Id': 'string',
        'Name': 'string',
        'CallerReference': 'string',
        'Config': {
            'Comment': 'string',
            'PrivateZone': True|False
        },
        'ResourceRecordSetCount': 123,
        'LinkedService': {
            'ServicePrincipal': 'string',
            'Description': 'string'
        }
    },
    'ChangeInfo': {
        'Id': 'string',
        'Status': 'PENDING'|'INSYNC',
        'SubmittedAt': datetime(2015, 1, 1),
        'Comment': 'string'
    },
    'DelegationSet': {
        'Id': 'string',
        'CallerReference': 'string',
        'NameServers': [
            'string',
        ]
    },
    'VPC': {
        'VPCRegion': 'us-east-1'|'us-east-2'|'us-west-1'|'us-west-2'|'eu-west-1'|'eu-west-2'|'eu-west-3'|'eu-central-1'|'eu-central-2'|'ap-east-1'|'me-south-1'|'us-gov-west-1'|'us-gov-east-1'|'us-iso-east-1'|'us-iso-west-1'|'us-isob-east-1'|'me-central-1'|'ap-southeast-1'|'ap-southeast-2'|'ap-southeast-3'|'ap-south-1'|'ap-south-2'|'ap-northeast-1'|'ap-northeast-2'|'ap-northeast-3'|'eu-north-1'|'sa-east-1'|'ca-central-1'|'cn-north-1'|'af-south-1'|'eu-south-1'|'eu-south-2'|'ap-southeast-4'|'il-central-1'|'ca-west-1'|'ap-southeast-5',
        'VPCId': 'string'
    },
    'Location': 'string'
}

Response Structure

• (dict) –

  A complex type containing the response information for the hosted zone.

  • HostedZone (dict) –

    A complex type that contains general information about the hosted zone.

    • Id (string) –

      The ID that Amazon Route 53 assigned to the hosted zone when you created it.

    • Name (string) –

      The name of the domain. For public hosted zones, this is the name that you have registered with your DNS registrar.

      For information about how to specify characters other than a-z, 0-9, and - (hyphen) and how to specify internationalized domain names, see CreateHostedZone.

    • CallerReference (string) –

      The value that you specified for CallerReference when you created the hosted zone.

    • Config (dict) –

      A complex type that includes the Comment and PrivateZone elements. If you omitted the HostedZoneConfig and Comment elements from the request, the Config and Comment elements don’t appear in the response.

      • Comment (string) –

        Any comments that you want to include about the hosted zone.

      • PrivateZone (boolean) –

        A value that indicates whether this is a private hosted zone.

    • ResourceRecordSetCount (integer) –

      The number of resource record sets in the hosted zone.

    • LinkedService (dict) –

      If the hosted zone was created by another service, the service that created the hosted zone. When a hosted zone is created by another service, you can’t edit or delete it using Route 53.

      • ServicePrincipal (string) –

        If the health check or hosted zone was created by another service, the service that created the resource. When a resource is created by another service, you can’t edit or delete it using Amazon Route 53.

      • Description (string) –

        If the health check or hosted zone was created by another service, an optional description that can be provided by the other service. When a resource is created by another service, you can’t edit or delete it using Amazon Route 53.

  • ChangeInfo (dict) –

    A complex type that contains information about the CreateHostedZone request.

    • Id (string) –

      This element contains an ID that you use when performing a GetChange action to get detailed information about the change.

    • Status (string) –

      The current state of the request. PENDING indicates that this request has not yet been applied to all Amazon Route 53 DNS servers.

    • SubmittedAt (datetime) –

      The date and time that the change request was submitted in ISO 8601 format and Coordinated Universal Time (UTC). For example, the value 2017-03-27T17:48:16.751Z represents March 27, 2017 at 17:48:16.751 UTC.

    • Comment (string) –

      A comment you can provide.

  • DelegationSet (dict) –

    A complex type that describes the name servers for this hosted zone.

    • Id (string) –

      The ID that Amazon Route 53 assigns to a reusable delegation set.

    • CallerReference (string) –

      The value that you specified for CallerReference when you created the reusable delegation set.

    • NameServers (list) –

      A complex type that contains a list of the authoritative name servers for a hosted zone or for a reusable delegation set.

      • (string) –

  • VPC (dict) –

    A complex type that contains information about an Amazon VPC that you associated with this hosted zone.

    • VPCRegion (string) –

      (Private hosted zones only) The region that an Amazon VPC was created in.

    • VPCId (string) –

      (Private hosted zones only) The ID of an Amazon VPC.

  • Location (string) –

    The unique URL representing the new hosted zone.

Exceptions

• Route53.Client.exceptions.InvalidDomainName

• Route53.Client.exceptions.HostedZoneAlreadyExists

• Route53.Client.exceptions.TooManyHostedZones

• Route53.Client.exceptions.InvalidVPCId

• Route53.Client.exceptions.InvalidInput

• Route53.Client.exceptions.DelegationSetNotAvailable

• Route53.Client.exceptions.ConflictingDomainExists

• Route53.Client.exceptions.NoSuchDelegationSet

• Route53.Client.exceptions.DelegationSetNotReusable