# AWS Cloud Map namespaces A namespace is a logical entity in AWS Cloud Map that is used to group an application's services under a common name and level of discoverability. When you create a namespace, you specify the following: + A name that you want your application to use to discover instances. + The method by which service instances that you register with AWS Cloud Map can be discovered. You can decide whether your resources need to be discovered publicly over the internet, privately in a specific virtual private cloud (VPC), or by API calls only. The following are general concepts about namespaces. + Namespaces are specific to the AWS Region that they're created in. To use AWS Cloud Map in multiple regions, you'll need to create namespaces in each region. + If you create a namespace to allow for instance discovery by DNS queries in a VPC, AWS Cloud Map automatically creates a private Route 53 hosted zone. This hosted zone can be associated with multiple VPCs. For more information, see [AssociateVPCWithHostedZone](https://docs.aws.amazon.com/Route53/latest/APIReference/API_AssociateVPCWithHostedZone.html) in the *Amazon Route 53 API Reference*. **Topics** + [Creating an AWS Cloud Map namespace to group application services](creating-namespaces.md) + [Listing AWS Cloud Map namespaces](listing-namespaces.md) + [Deleting an AWS Cloud Map namespace](deleting-namespaces.md) + [Shared AWS Cloud Map namespaces](sharing-namespaces.md) # Creating an AWS Cloud Map namespace to group application services You can create a namespace to group services for your application under a friendly name that allows for the discovery of application resources through API calls or DNS queries. ## Instance discovery options The following table summarizes the different instance discovery options in AWS Cloud Map and the corresponding namespace type that you can create, depending on your application's services and setup. | Namespace type | Instance discovery method | How it works | Additional information | | --- | --- | --- | --- | | HTTP | API calls | Resources in your application can discover other resources by calling the DiscoverInstances API only. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloud-map/latest/dg/creating-namespaces.html) | | Private DNS | API calls and DNS queries in a VPC | When you create a private DNS namespace, AWS Cloud Map creates a corresponding Amazon Route 53 private hosted zone. Resources in your application can discover other resources by calling the `DiscoverInstances` API, and by querying the nameservers in the private Route 53 hosted zone that AWS Cloud Map automatically creates. The hosted zone created by AWS Cloud Map has the same name as the namespace and contains DNS records that have names in the format *service-name*.*namespace-name*. 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). | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloud-map/latest/dg/creating-namespaces.html) | | Public DNS | API calls and public DNS queries | When you create a public DNS namespace, AWS Cloud Map creates a corresponding Amazon Route 53 public hosted zone. Resources in your application can discover other resources by calling the `DiscoverInstances` API and by querying the nameservers in the public Route 53 hosted zone that AWS Cloud Map automatically creates. The public hosted zone has the same name as the namespace and contains DNS records that have names in the format *service-name*.*namespace-name*. The namespace name in this case must be a domain name that you've registered. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloud-map/latest/dg/creating-namespaces.html) | ## Procedure You can follow these steps to create a namespace using the AWS CLI, AWS Management Console, or the SDK for Python. ------ #### [ AWS Management Console ] 1. Sign in to the AWS Management Console and open the AWS Cloud Map console at [https://console.aws.amazon.com/cloudmap/](https://console.aws.amazon.com/cloudmap/). 1. Choose **Create namespace**. 1. For **Namespace name**, enter a name that will be used to discover instances. **Note** Namespaces configured for public DNS queries must end with a top level domain. For example, `.com`. 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. 1. (Optional) For **Namespace description**, enter information about the namespace that will be visible on the **Namespaces** page and under **Namespace information**. You can use this information to easily identify a namespace. 1. For **Instance discovery**, you can choose between **API calls**, **API calls and DNS queries in VPCs**, and **API calls and public DNS queries** to create a HTTP, private DNS, or public DNS namespace respectively. For more information, see [Instance discovery options](#working-with-namespaces-instance-discovery). Based on your selection, follow these steps. + If you choose **API calls and DNS queries in VPCs**, for **VPC**, choose a virtual private cloud (VPC) that you want to associate the namespace with. + If you choose **API calls and DNS queries in VPCs** or **API calls and public DNS queries**, for **TTL**, specify a numerical value in seconds. The time to live (TTL) value determines how long DNS resolvers cache information for the start of authority (SOA) DNS record of the Route 53 hosted zone created with your namespace. For more information about TTL, see [TTL (seconds)](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resource-record-sets-values-shared.html#rrsets-values-common-ttl) in the *Amazon Route 53 Developer Guide*. 1. (Optional) Under **Tags**, choose **Add tags** and then specify a key and a value to tag your namespace. You can specify one or more tags to add to your namespace. Tags allow you to categorize your AWS resources so you can more easily manage them. For more information, see [Tagging your AWS Cloud Map resources](using-tags.md). 1. Choose **Create namespace**. You can view the status of the operation by using [ListOperations](https://docs.aws.amazon.com/cloud-map/latest/api/API_ListOperations.html). For more information, see [ListOperations](https://docs.aws.amazon.com/cloud-map/latest/api/API_ListOperations.html) in the *AWS Cloud Map API Reference* ------ #### [ AWS 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](https://docs.aws.amazon.com/cli/latest/reference/servicediscovery/create-http-namespace.html)`. 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](https://docs.aws.amazon.com/cli/latest/reference/servicediscovery/create-private-dns-namespace.html)`. 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](https://docs.aws.amazon.com/cli/latest/reference/servicediscovery/create-public-dns-namespace.html)`. 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 ``` ------ #### [ AWS SDK for Python (Boto3) ] 1. If you don't already have `Boto3` installed, you can find instructions for installing, configuring, and using `Boto3` [here](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html#installation). 1. Import `Boto3` and use `servicediscovery` as your service. ``` import boto3 client = boto3.client('servicediscovery') ``` 1. 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': { '...': '...', }, } ``` ------ ## Next steps After creating a namespace, you can create services in the namespace to group together application resources that collectively serve a particular purpose in your application. A service acts as a template for registering application resources as instances. For more information about creating AWS Cloud Map services, see [Creating an AWS Cloud Map service for an application component](creating-services.md). # Listing AWS Cloud Map namespaces After creating namespaces, you can view a list of the namespaces you've created by following these steps. ------ #### [ AWS Management Console ] 1. Sign in to the AWS Management Console and open the AWS Cloud Map console at [https://console.aws.amazon.com/cloudmap/](https://console.aws.amazon.com/cloudmap/). 1. In the navigation pane, choose **Namespaces** to view a list of namespaces. You can order namespaces by name, description, instance discovery mode, owner, or namespace ID. You can also enter a namespace name or ID into the search field to locate and view a specific namespace. ------ #### [ AWS CLI ] + List namespaces with the `[list-namespaces](https://docs.aws.amazon.com/cli/latest/reference/servicediscovery/list-namespaces.html)` command. ``` aws servicediscovery list-namespaces ``` ------ #### [ AWS SDK for Python (Boto3) ] 1. If you don't already have `Boto3` installed, you can find instructions for installing, configuring, and using `Boto3` [here](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html#installation). 1. Import `Boto3` and use `servicediscovery` as your service. ``` import boto3 client = boto3.client('servicediscovery') ``` 1. List namespaces with `list_namespaces()`. ``` response = client.list_namespaces() # If you want to see the response print(response) ``` Example response output ``` { 'Namespaces': [ { 'Arn': 'arn:aws::servicediscovery:us-west-2:123456789012:namespace/ns-xxxxxxxxxxxxxxx', 'CreateDate': 1585354387.357, 'Id': 'ns-xxxxxxxxxxxxxxx', 'Name': 'myFirstNamespace', 'Properties': { 'DnsProperties': { 'HostedZoneId': 'Z06752353VBUDTC32S84S', }, 'HttpProperties': { 'HttpName': 'myFirstNamespace', }, }, 'Type': 'DNS_PRIVATE', }, { 'Arn': 'arn:aws::servicediscovery:us-west-2:123456789012:namespace/ns-xxxxxxxxxxxxxxx', 'CreateDate': 1586468974.698, 'Description': 'My second namespace', 'Id': 'ns-xxxxxxxxxxxxxxx', 'Name': 'mySecondNamespace.com', 'Properties': { 'DnsProperties': { }, 'HttpProperties': { 'HttpName': 'mySecondNamespace.com', }, }, 'Type': 'HTTP', }, { 'Arn': 'arn:aws::servicediscovery:us-west-2:123456789012:namespace/ns-xxxxxxxxxxxxxxx', 'CreateDate': 1587055896.798, 'Id': 'ns-xxxxxxxxxxxxxxx', 'Name': 'myThirdNamespace.com', 'Properties': { 'DnsProperties': { 'HostedZoneId': 'Z09983722P0QME1B3KC8I', }, 'HttpProperties': { 'HttpName': 'myThirdNamespace.com', }, }, 'Type': 'DNS_PRIVATE', }, ], 'ResponseMetadata': { '...': '...', }, } ``` ------ # Deleting an AWS Cloud Map namespace After you're done using a namespace, you can delete it. When you delete a namespace, you can no longer use it to register or discover service instances. **Note** When you delete a DNS namespace, AWS Cloud Map deletes the corresponding Amazon Route 53 hosted zone created during namespace creation. Before deleting a namespace, you must deregister all service instances and then delete all services that were created in the namespace. For more information, see [Deregistering an AWS Cloud Map service instance](deregistering-instances.md) and [Deleting an AWS Cloud Map service](deleting-services.md). After you've deregistered instances and deleted services that were created in a namespace, follow these steps to delete the namespace. ------ #### [ AWS Management Console ] 1. Sign in to the AWS Management Console and open the AWS Cloud Map console at [https://console.aws.amazon.com/cloudmap/](https://console.aws.amazon.com/cloudmap/). 1. In the navigation pane, choose **Namespaces**. 1. Select the namespace that you want to delete, then choose **Delete**. 1. Confirm that you want to delete the service by choosing **Delete** again. ------ #### [ AWS CLI ] + Delete a namespace with the `[delete-namespace](https://docs.aws.amazon.com/cli/latest/reference/servicediscovery/delete-namespace.html)` command (replace the *red* value with your own). If the namespace still contains one or more services, the request fails. ``` aws servicediscovery delete-namespace --id ns-xxxxxxxxxxx ``` ------ #### [ AWS SDK for Python (Boto3) ] 1. If you don't already have `Boto3` installed, you can find instructions for installing, configuring, and using `Boto3` [here](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html#installation). 1. Import `Boto3` and use `servicediscovery` as your service. ``` import boto3 client = boto3.client('servicediscovery') ``` 1. Delete a namespace with `delete_namespace()` (replace the *red* value with your own). If the namespace still contains one or more services, the request fails. ``` response = client.delete_namespace( Id='ns-xxxxxxxxxxx', ) # If you want to see the response print(response) ``` Example response output ``` { 'OperationId': 'gv4g5meo7ndmeh4fqskygvk23d2fijwa-k98y6drk', 'ResponseMetadata': { '...': '...', }, } ``` ------ # Shared AWS Cloud Map namespaces AWS Cloud Map allows namespace owners to share their namespaces with other AWS accounts or within an organization in AWS Organizations for simplified cross-account service discovery and service registry. This allows for easier use of namespaces managed by other AWS accounts or teams within an AWS Organization. AWS Cloud Map integrates with AWS Resource Access Manager (AWS RAM) to enable resource sharing. AWS RAM is a service that enables you to share some AWS Cloud Map resources with other AWS accounts or through AWS Organizations. With AWS RAM, you share resources that you own by creating a *resource share*. A resource share specifies the resources to share, and the consumers with whom to share them. Consumers can include: + Specific AWS accounts inside its organization in AWS Organizations + An organizational unit inside its organization in AWS Organizations + Its entire organization in AWS Organizations For more information about AWS RAM, see the *[AWS RAM User Guide](https://docs.aws.amazon.com/ram/latest/userguide/)*. This topic explains how to share resources that you own, and how to use resources that are shared with you. **Topics** + [Considerations for sharing namespaces](#sharing-considerations) + [Sharing an AWS Cloud Map namespace](sharing-share.md) + [Stop sharing a AWS Cloud Map namespace](sharing-unshare.md) + [Identifying a shared AWS Cloud Map namespace](sharing-identify.md) + [Granting permissions to share a namespace](#granting-perms-to-share) + [Responsibilities and permissions for shared namespaces](#sharing-perms) + [Billing and metering](#sharing-billing) + [Quotas](#sharing-quotas) ## Considerations for sharing namespaces + To share a namespace, you must own it in your AWS account. This means that the resource must be allocated or provisioned in your account. You can't share a namespace that has been shared with you. + To share a namespace with your organization or an organizational unit in AWS Organizations, you must enable sharing with AWS Organizations. For more information, see [ Enable Sharing with AWS Organizations](https://docs.aws.amazon.com/ram/latest/userguide/getting-started-sharing.html#getting-started-sharing-orgs) in the *AWS RAM User Guide*. + For service discovery using DNS queries in a shared private DNS namespace, the namespace owner will need to call `create-vpc-association-authorization` with the ID of the private hosted zone associated with the namespace and the consumer's VPC. ``` aws route53 create-vpc-association-authorization --hosted-zone-id Z1234567890ABC --vpc VPCRegion=us-east-1,VPCId=vpc-12345678 ``` The namespace consumer will need to call `associate-vpc-with-hosted-zone` with the ID of the private hosted zone. ``` aws route53 associate-vpc-with-hosted-zone --hosted-zone-id Z1234567890ABC --vpc VPCRegion=us-east-1,VPCId=vpc-12345678 ``` For more information, see [Associating an Amazon VPC and a private hosted zone that you created with different AWS accounts](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zone-private-associate-vpcs-different-accounts.html) in the *Amazon Route 53 Developer Guide*. + After discovering up-to-date network locations of services associated with a shared DNS namespace, it may be necessary to configure inter-VPC connectivity to communicate with the services if they are in different VPCs. This can be achieved using a VPC Peering connection. For more information, see [Create or delete a VPC Peering connection](https://docs.aws.amazon.com/vpc/latest/peering/create-vpc-peering-connection.html) in the *Amazon Virtual Private Cloud VPC Peering guide*. + You can't use `ListOperations` to list operations on shared namespaces that are performed by other accounts. + Tagging isn't supported for shared namespaces. # Sharing an AWS Cloud Map namespace When you share an AWS Cloud Map namespace that you own with other AWS accounts (consumers), you enable these accounts to discover the up-to-date network locations of services in the namespace without the need for temporary credentials. To share a namespace, you must add it to a resource share. A resource share is an AWS RAM resource that lets you share your resources across AWS accounts. A resource share specifies the resources to share, and the consumers with whom they are shared. To add the namespace to a new resource share, you must first create the resource share using the [AWS RAM console](https://console.aws.amazon.com/ram). If you are part of an organization in AWS Organizations and sharing within your organization is enabled, consumers in your organization are automatically granted access to the shared namespace. Otherwise, consumers receive an invitation to join the resource share and are granted access to the shared namespace after accepting the invitation. You can share a namespace that you own using the AWS RAM console or the AWS CLI. ------ #### [ AWS RAM console ] **To share a namespace that you own using the AWS RAM console** See [Creating a resource share in AWS RAM](https://docs.aws.amazon.com/ram/latest/userguide/working-with-sharing-create.html) in the *AWS RAM User Guide*. ------ #### [ AWS CLI ] **To share a namespace that you own using the AWS CLI** Use the AWS RAM [create-resource-share](https://docs.aws.amazon.com/cli/latest/reference/ram/create-resource-share.html) command. ------ # Stop sharing a AWS Cloud Map namespace When a namespace is no longer shared, the namespace and any services and instances associated with it can no longer be accessed by consumer AWS accounts. This includes resources created in the namespace by consumers when they had access to the namespace. To stop sharing a namespace that you own, you must remove it from the resource share. You can do this using the AWS RAM console or the AWS CLI. ------ #### [ AWS RAM console ] **To stop sharing a namespace that you own using the AWS RAM console** See [Updating a Resource Share](https://docs.aws.amazon.com/ram/latest/userguide/working-with-sharing-update.html) in the *AWS RAM User Guide*. ------ #### [ AWS CLI ] **To stop sharing a namespace that you own using the AWS CLI** Use the [disassociate-resource-share](https://docs.aws.amazon.com/cli/latest/reference/ram/disassociate-resource-share.html) command. ------ # Identifying a shared AWS Cloud Map namespace Owners and consumers can identify shared namespaces using the AWS Cloud Map console and AWS CLI. The namespace owner can be identified by using the `ResourceOwner` property. The AWS account that creates a service or registers an instance in the shared namespace can be identified by using the `CreatedByAccount` property. ------ #### [ AWS Cloud Map console ] **To identify a shared namespace using the AWS Cloud Map console** 1. Sign in to the AWS Management Console and open the AWS Cloud Map console at [https://console.aws.amazon.com/cloudmap/](https://console.aws.amazon.com/cloudmap/). 1. On the **Namespaces** page, under **Resource Owner**, you can find the ID of the AWS account that owns the namespace. 1. Choose the **Domain name** of the namespace you want to identify. 1. On the **Namespace: *namespace-name*** page, in the **Namespace information** section, under **Resource owner**, you can find the ID of the AWS account that owns the namespace. ------ #### [ AWS CLI ] To identify a shared namespace using the AWS CLI, use the [list-namespaces](https://docs.aws.amazon.com/cli/latest/reference/servicediscovery/list-namespaces.html) command. The command returns the namespaces that you own and namespaces that are shared with you. The `ResourceOwner` field shows the AWS account ID of the namespace owner. The following `list-namespaces` call is made by account `111122223333`. ``` aws servicediscovery list-namespaces ``` Output: ``` { "Namespaces": [ { "Arn": "arn:aws:servicediscovery:us-west-2:111122223333:namespace/ns-abcdef01234567890", "CreateDate": 1585354387.357, "Id": "ns-abcdef01234567890", "Name": "local", "Properties": { "DnsProperties": { "HostedZoneId": "Z06752353VBUDTC32S84S" }, "HttpProperties": { "HttpName": "local" } }, "Type": "DNS_PRIVATE", "ServiceCount": 2, "ResourceOwner": "111122223333" }, { "Arn": "arn:aws:servicediscovery:us-west-2:444455556666:namespace/ns-021345abcdef6789", "CreateDate": 1586468974.698, "Description": "Shared second namespace", "Id": "ns-021345abcdef6789", "Name": "My-second-namespace", "Properties": { "DnsProperties": {}, "HttpProperties": { "HttpName": "Shared-second-namespace" } }, "Type": "HTTP", "ServiceCount": 0, "ResourceOwner": "444455556666" } ] } ``` In this scenario, namespace `ns-abcdef01234567890` is created and owned by `111122223333` and namespace `ns-021345abcdef6789` is created and owned by `444455556666`. Namespace `ns-021345abcdef6789` is shared with account `111122223333` by account `444455556666`. ------ ## Granting permissions to share a namespace A minimum set of permissions is required for an IAM principal to share a namespace. We recommend using the `AWSCloudMapFullAccess` and `AWSResourceAccessManagerFullAccess` managed policies to ensure your IAM principals have the required permissions to share and use shared namespaces. If you use a custom IAM policy, the `servicediscovery:PutResourcePolicy`, `servicediscovery:GetResourcePolicy`, and `servicediscovery:DeleteResourcePolicy` actions are required for sharing namespaces. These are permission-only IAM actions. If an IAM principal doesn't have these permissions granted, an error will occur when attempting to share the namespace using AWS RAM. For more information about how AWS RAM uses IAM, see [How AWS RAM uses IAM](https://docs.aws.amazon.com/ram/latest/userguide/security-iam-policies.html) in the *AWS RAM User Guide*. ## Responsibilities and permissions for shared namespaces The namespace owner and consumer can perform different actions on a shared namespace. ### Permissions for owners A namespace owner can perform the following actions on a shared namespace: + Access services associated with the namespace, including services created by consumer accounts and instances registered to these services. + Revoke access to the namespace, including access to services created by consumer accounts and instances registered to these services. + Configure permissions for other accounts to register and deregister instances in services created in the shared namespace by consumers or the namespace owner. + Delete services and deregister instances, including services created and instances registered by consumer accounts. + Update or delete a shared namespace. ### Permissions for consumers A namespace consumer can perform the following actions on a shared namespace: + Create and delete services in the namespace. + Register and deregister instances in services created in the namespace. + Discover instances that are registered to services created in the namespace. A consumer can't update or delete a shared namespace. After losing access to the shared namespace, the consumer accounts will also lose access to services that they created in the namespace. ## Billing and metering Owners are billed for any instances that they register in the shared namespace and any Route 53 health checks that are created when they register these instances. Consumers are billed for any instances that they register in the namespace and any Route 53 health checks that are created when they register these instances. If the shared namespace is a DNS namespace, the namespace owner is billed for the Route 53 DNS records that are created when services are created in the namespace. Owners are billed for any `DiscoverInstances` and `DiscoverInstancesRevision` calls they make. Consumers are billed for any `DiscoverInstances` and `DiscoverInstancesRevision` calls they make. ## Quotas Shared namespaces count towards only the namespace owner's namespaces per Region quota. Instances registered by a consumer in the shared namespace count towards the owner's instances per namespace quota. If a consumer creates a service in a shared namespace, any instances registered in the service count towards the consumer's instances per service quota. If an owner creates a service in a shared namespace, any instances registered in the service count towards the owner's instances per service quota.