Creating an Amazon Cloud Map namespace - Amazon Cloud Map
Values that you specify when you create a namespace
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Creating an Amazon Cloud Map namespace

To create a namespace, perform the following procedure.

Amazon Web Services Management Console

  1. Sign in to the Amazon Web Services Management Console and open the Amazon Cloud Map console at https://console.amazonaws.cn/cloudmap/.

  2. Choose Create namespace.

  3. On the Create namespace page, enter the applicable values. For more information, see Values that you specify when you create a namespace.

  4. Choose Create namespace.

Amazon CLI

  • Create a namespace with the command for the instance discovery type you would prefer (replace the red values with your own).

    • Create an HTTP namespace using create-http-namespace. Service instances registered using an HTTP namespace can be discovered using a DiscoverInstances request, but they can't be discovered using DNS.

      aws servicediscovery create-http-namespace --name name-of-namespace

    • Create a private namespace based on DNS and only visible inside a specified Amazon VPC using create-private-dns-namespace. You can discover instances that were registered with a private DNS namespace by using either a DiscoverInstances request or using DNS

      aws servicediscovery create-private-dns-namespace --name name-of-namespace --vpc vpc-xxxxxxxxx

    • Create a public namespace based on DNS that is visible on the internet using create-public-dns-namespace. You can discover instances that were registered with a public DNS namespace by using either a DiscoverInstances request or using DNS.

      aws servicediscovery create-public-dns-namespace --name name-of-namespace
      Note
      Namespace requirements:

      • Namespaces configured for public DNS queries must end with a top level domain (e.g .com).

      • The namespace name can have up to 1,024 characters, and must start and end with a letter.

      • Valid characters: a-z, A-Z, 0-9, . (period), _ (underscore), and - (hyphen).

Amazon SDK for Python (Boto3)

  1. If you don't already have Boto3 installed, you can find instructions for installing, configuring, and using Boto3 here.

  2. Import Boto3 and use servicediscovery as your service.

    import boto3
client = boto3.client('servicediscovery')

  3. Create a namespace with the command for the instance discovery type you would prefer (replace the red values with your own):

    • Create an HTTP namespace using create_http_namespace(). Service instances registered using an HTTP namespace can be discovered using discover_instances(), but they can't be discovered using DNS.

      response = client.create_http_namespace(
    Name='name-of-namespace',
)
# If you want to see the response
print(response)

    • Create a private namespace based on DNS and only visible inside a specified Amazon VPC using create_private_dns_namespace(). You can discover instances that were registered with a private DNS namespace by using either discover_instances() or using DNS

      response = client.create_private_dns_namespace(
    Name='name-of-namespace',
    Vpc='vpc-1c56417b',
)
# If you want to see the response
print(response)

    • Create a public namespace based on DNS that is visible on the internet using create_public_dns_namespace(). You can discover instances that were registered with a public DNS namespace by using either discover_instances() or using DNS.

      response = client.create_public_dns_namespace(
    Name='name-of-namespace',
)
# If you want to see the response
print(response)

    • Example response output

      {
    'OperationId': 'gv4g5meo7ndmeh4fqskygvk23d2fijwa-k9302yzd',
    'ResponseMetadata': {
        '...': '...',
    },
}
      Note
      Namespace requirements:

      • Namespaces configured for public DNS queries must end with a top level domain (e.g .com).

      • The namespace name can have up to 1,024 characters, and must start and end with a letter.

      • Valid characters: a-z, A-Z, 0-9, . (period), _ (underscore), and - (hyphen).

Values that you specify when you create a namespace

When you create an Amazon Cloud Map namespace, you specify the following values.

Note

After you create a namespace, you can change tags. However, you can't change any other values.

Values

Namespace name

The name that you specify for a namespace depends on how you want your application to discover instances. The method of how instances are discovered is determined by the option that you choose for Instance discovery. The options appear later on the current page in the console. They are as follows:

API calls

If you choose this option, your application discovers service instances by specifying the namespace name and service name in a DiscoverInstances request. For more information, see DiscoverInstances in the Amazon Cloud Map API Reference.

You can specify a name that's up to 1,024 characters in length. A name can contain both uppercase and lowercase letters, numbers, underscores (_), and hyphens (-).

API calls and DNS queries in VPCs

Enter the domain name that you want your applications in a VPC to use when they discover instances by submitting DNS queries. Amazon Cloud Map automatically creates an Amazon Route 53 private hosted zone that has this name. When you register service instances, Amazon Cloud Map creates DNS records in the hosted zone that have names in the following format:

service-name.namespace-name

If you choose this option, your application can also discover instances by specifying the namespace name and service name in a DiscoverInstances request. For more information, see DiscoverInstances in the Amazon Cloud Map API Reference.

You can specify an internationalized domain name (IDN) if you convert the name to Punycode first. For information about online converters, perform an internet search on "punycode converter".

You can also convert an internationalized domain name to Punycode when you create namespaces programmatically. For example, if you're using Java, you can convert a Unicode value to Punycode by using the toASCII method of the java.net.IDN library.

API calls and public DNS queries

Enter the domain name that you want your applications to use when they discover instances by submitting public DNS queries. This must be a domain name that you have registered. When you create the namespace, Amazon Cloud Map automatically creates an Amazon Route 53 public hosted zone that has the same name. When you register service instances, Amazon Cloud Map creates DNS records in the hosted zone that have names in the following format:

service-name.namespace-name

If you choose this option, your application can also discover instances by specifying the namespace name and service name in a DiscoverInstances request. For more information, see DiscoverInstances in the Amazon Cloud Map API Reference.

You can specify an internationalized domain name (IDN) if you convert the name to Punycode first. For information about online converters, perform an internet search on "punycode converter".

You can also convert an internationalized domain name to Punycode when you create namespaces programmatically. For example, if you're using Java, you can convert a Unicode value to Punycode by using the toASCII method of the java.net.IDN library.

Namespace description

Enter a description for the namespace. The value that you enter here appears on the Namespaces page and on the detail page for each namespace.

Instance discovery

Choose how you want your application to discover registered instances:

API calls

Choose this option if you want your application to use only API calls to discover registered instances.

API calls and DNS queries in VPCs

Choose this option if you want your application to be able to discover instances using either API calls or using DNS queries in a VPC. You aren't required to use both methods.

API calls and public DNS queries

Choose this option if you want your application to be able to discover instances using either API calls or using public DNS queries. You aren't required to use both methods.

SOA TTL

For API calls and DNS queries in VPCs or API calls and public DNS queries, the time to live (TTL) value for the start of authority (SOA) DNS record of the Route 53 hosted zone created with your namespace. The value determines how long DNS resolvers cache information for this record before the resolvers forward another DNS query to Amazon Route 53 to get updated settings. A smaller value will also reduce the time a missing entry will be cached (negative caching) at the expense of additional queries for that namespace.

Tags

You can specify one or more tags to add to your namespace. A tag is an optional label that you can assign to an Amazon resource. Each tag consists of a key and a value. For example, you can define a tag with Key = Environment and Value = Production. Tags enable you to categorize your Amazon resources so you can more easily manage them.

You can update or remove tags on your namespaces after they have been created. For more information, see Tagging your Amazon Cloud Map resources.

VPC

When you choose API calls and DNS queries in VPCs for the value of Instance discovery, Amazon Cloud Map creates an Amazon Route 53 private hosted zone that has the same name. Amazon Cloud Map associates the VPC that you choose in the VPC list with that private hosted zone.

Route 53 Resolver resolves DNS queries that originate in the VPC using records in the private hosted zone. If the private hosted zone doesn't include a record that matches the domain name in a DNS query, Route 53 responds to the query with NXDOMAIN (non-existent domain).

You can associate additional VPCs with the private hosted zone. For more information, see AssociateVPCWithHostedZone in the Amazon Route 53 API Reference.