# Amazon ECS Service Connect with shared AWS Cloud Map namespaces
Amazon ECS Service Connect supports using shared AWS Cloud Map namespaces across multiple AWS accounts within the same AWS Region. This capability enables you to create distributed applications where services running in different AWS accounts can discover and communicate with each other through Service Connect. Shared namespaces are managed using AWS Resource Access Manager (AWS RAM), which allows secure cross-account resource sharing. For more information about shared namespaces, see [Cross-account AWS Cloud Map namespace sharing](https://docs.aws.amazon.com/cloud-map/latest/dg/sharing-namespaces.html) in the *AWS Cloud Map Developer Guide*.
**Important**
You must use the `AWSRAMPermissionCloudMapECSFullPermission` managed permission to share the namespace for Service Connect to work properly with the namespace.
When you use shared AWS Cloud Map namespaces with Service Connect, services from multiple AWS accounts can participate in the same service namespace. This is particularly useful for organizations with multiple AWS accounts that need to maintain service-to-service communication across account boundaries while preserving security and isolation.
**Note**
To communicate with services that are in different VPCs, you will need to configure inter-VPC connectivity. 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*.
# Using shared AWS Cloud Map namespaces with Amazon ECS Service Connect
Setting up shared AWS Cloud Map namespaces for Service Connect involves the following steps: Namespace owner creating the namespace, owner sharing it through AWS Resource Access Manager (AWS RAM), consumer accepting the resource share, and consumer configuring Service Connect to use the shared namespace.
## Step 1: Create the AWS Cloud Map namespace
The namespace owner creates a AWS Cloud Map namespace that will be shared with other accounts.
**To create a namespace for sharing using the AWS Management Console**
1. Open the AWS Cloud Map console at [https://console.aws.amazon.com/cloudmap/](https://console.aws.amazon.com/cloudmap/).
1. Choose **Create namespace**.
1. Enter a **Namespace name**. This name will be used by services across all participating accounts.
1. For **Namespace type**, choose the appropriate type for your use case:
+ **API calls** ‐ HTTP namespaces for service discovery without DNS functionality.
+ **API calls and DNS queries in VPCs** ‐ Private DNS namespaces for service discovery with private DNS queries in a VPC.
+ **API calls and public DNS queries** ‐ Public DNS namespaces for service discovery with public DNS queries.
1. Choose **Create namespace**.
## Step 2: Share the namespace using AWS RAM
The namespace owner uses AWS RAM to share the namespace with other AWS accounts.
**To share a namespace using the AWS RAM console**
1. Open the AWS RAM console at [https://console.aws.amazon.com/ram/](https://console.aws.amazon.com/ram/).
1. Choose **Create resource share**.
1. For **Name**, enter a descriptive name for the resource share.
1. In the **Resources** section:
1. For **Resource type**, choose **Cloud Map Namespaces**.
1. Select the namespace you created in the previous step.
1. In the **Managed permissions** section, specify **AWSRAMPermissionCloudMapECSFullPermission**.
**Important**
You must use the `AWSRAMPermissionCloudMapECSFullPermission` managed permission to share the namespace for Service Connect to work properly with the namespace.
1. In the **Principals** section, specify the AWS accounts you want to share the namespace with. You can enter account IDs or organizational unit IDs.
1. Choose **Create resource share**.
## Step 3: Accept the resource share
Namespace consumer accounts must accept the resource share invitation to use the shared namespace.
**To accept a resource share invitation using the AWS RAM console**
1. In the consumer account, open the AWS RAM console at [https://console.aws.amazon.com/ram/](https://console.aws.amazon.com/ram/).
1. In the navigation pane, choose **Shared with me**, then choose **Resource shares**.
1. Select the resource share invitation and choose **Accept resource share**.
1. After accepting, note the shared namespace ARN from the resource details. You'll use this ARN when configuring Service Connect services.
## Step 4: Configure an Amazon ECS service with the shared namespace
After accepting the shared namespace, the namespace consumer can configure Amazon ECS services to use the shared namespace. The configuration is similar to using a regular namespace, but you must specify the namespace ARN instead of the name. For a detailed service creation procedure, see [Creating an Amazon ECS rolling update deployment](create-service-console-v2.md).
**To create a service with a shared namespace using the AWS Management Console**
1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2).
1. On the **Clusters** page, choose the cluster that you want to create the service in.
1. Under **Services**, choose **Create**.
1. After filling in other details depending on your workload, in the **Service Connect** section, choose **Use Service Connect**.
1. For **Namespace**, enter the full ARN of the shared namespace.
The ARN format is: `arn:aws:servicediscovery:region:account-id:namespace/namespace-id`
1. Configure the remaining Service Connect settings as needed for your service type (client or client-server).
1. Complete the service creation process.
You can also configure services using the AWS CLI or AWS SDKs by specifying the shared namespace ARN in the `namespace` parameter of the `serviceConnectConfiguration`.
```
aws ecs create-service \
--cluster my-cluster \
--service-name my-service \
--task-definition my-task-def \
--service-connect-configuration '{
"enabled": true,
"namespace": "arn:aws:servicediscovery:us-west-2:123456789012:namespace/ns-abcdef1234567890",
"services": [{
"portName": "web",
"discoveryName": "my-service",
"clientAliases": [{
"port": 80,
"dnsName": "my-service"
}]
}]
}'
```
## Considerations
Consider the following when using shared AWS Cloud Map namespaces with Service Connect:
+ AWS RAM must be available in the AWS Region where you want to use the shared namespace.
+ The shared namespace must be in the same AWS Region as your Amazon ECS services and clusters.
+ You must use the namespace ARN, not the ID, when configuring Service Connect with a shared namespace.
+ All namespace types are supported: HTTP, Private DNS, and Public DNS namespaces.
+ If access to a shared namespace is revoked, Amazon ECS operations that require interaction with the namespace (such as `CreateService`, `UpdateService`, and `ListServicesByNamespace`) will fail. For more information about troubleshooting permissions issues with shared namespaces, see [Troubleshooting Amazon ECS Service Connect with shared AWS Cloud Map namespaces](service-connect-shared-namespaces-troubleshooting.md).
+ 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
```
+ Only the namespace owner can manage the resource share.
+ Namespace consumers can create and manage services within the shared namespace but cannot modify the namespace itself.
+ Discovery names must be unique within the shared namespace, regardless of which account creates the service.
+ Services in the shared namespace can discover and connect to services from other AWS accounts that have access to the namespace.
+ When enabling TLS for Service Connect and using a shared namespace, the AWS Private CA Certificate Authority (CA) is scoped to the namespace. When access to the shared namespace is revoked, access to the CA is stopped.
+ When working with a shared namespace, namespace owners and consumers don't have access to cross-account Amazon CloudWatch metrics by default. Target metrics are published only to accounts that own client services. An account that owns client services doesn't have access to metrics received by an account owning client-server services, and the other way around. To allow for cross-account access to metrics, set up CloudWatch cross-account observability. For more information about configuring cross-account observability, see [CloudWatch cross-account observabilty](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Unified-Cross-Account.html) in the *Amazon CloudWatch User Guide*. For more information about the CloudWatch metrics for Service Connect, see [Amazon ECS CloudWatch metrics](available-metrics.md).
# Troubleshooting Amazon ECS Service Connect with shared AWS Cloud Map namespaces
Use the following information to troubleshoot issues with shared AWS Cloud Map namespaces and Service Connect. For more information on locating error messages, see [Amazon ECS troubleshooting](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/troubleshooting.html).
Error messages related to permissions issues appear due to missing permissions, or if access to the namespace is revoked.
**Important**
You must use the `AWSRAMPermissionCloudMapECSFullPermission` managed permission to share the namespace for Service Connect to work properly with the namespace.
Error message appears in one of the following formats:
An error occurred (ClientException) when calling the operation: User: arn:aws:iam:::user/ is not authorized to perform: on resource: because no resource-based policy allows the action
The following scenarios can result in an error message in this format:
**Cluster creation or update failure**
These issues occur when Amazon ECS operations such as `CreateCluster` or `UpdateCluster` fail due to missing AWS Cloud Map permissions. The operations require permissions for the following AWS Cloud Map actions:
+ `servicediscovery:GetNamespace`
Ensure that the resource share invitation has been accepted in the consumer account and that the correct namespace ARN is being used in the Service Connect configuration.
**Service creation or update failure**
These issues occur when Amazon ECS operations such as `CreateService` or `UpdateService` fail due to missing AWS Cloud Map permissions. The operations require permissions for the following AWS Cloud Map actions:
+ `servicediscovery:CreateService`
+ `servicediscovery:GetNamespace`
+ `servicediscovery:GetOperation` (for creating a new AWS Cloud Map service)
+ `servicediscovery:GetService` (for when a AWS Cloud Map service already exists)
Ensure that the resource share invitation has been accepted in the consumer account and that the correct namespace ARN is being used in the Service Connect configuration.
**`ListServicesByNamespace` operation fails**
This issue occurs when the Amazon ECS `ListServicesByNamespace` operation fails. The operation requires permissions for the following AWS Cloud Map actions:
+ `servicediscovery:GetNamespace`
To resolve this issue:
+ Verify that the consumer account has the `servicediscovery:GetNamespace` permission.
+ Use the namespace ARN when calling the API, not the name.
+ Ensure the resource share is active and the invitation has been accepted.
User: is not authorized to perform: on resource: with an explicit deny in an identity-based policy.
The following scenarios can result in an error message in this format:
**Service deletion fails and gets stuck in `DRAINING` state**
This issue occurs when Amazon ECS `DeleteService` operations fail due to the missing `servicediscovery:DeleteService` permission when access to the namespace is revoked. The service may appear to delete successfully initially but will get stuck in the `DRAINING` state. The error message appears as an Amazon ECS service event.
To resolve this issue, the namespace owner must share the namespace with the consumer account to allow service deletion to complete.
**Tasks in service fail to run**
This issue occurs when tasks fail to start due to missing permissions. The error message is surfaced as a stopped task error. For more information, see [Resolve Amazon ECS stopped task errors](resolve-stopped-errors.md).
The following AWS Cloud Map actions are required for running a task:
+ `servicediscovery:GetOperation`
+ `servicediscovery:RegisterInstance`
Ensure that the consumer account has the required permissions and that the shared namespace is accessible.
**Tasks fail to stop cleanly or get stuck in `DEACTIVATING` or `DEPROVISIONING` state**
This issue occurs when tasks fail to deregister from the AWS Cloud Map service during shutdown due to missing permissions. The error is surfaced as a `statusReason` in the task attachment that can be retreived using the `DescribeTasks` API. For more information, see [DescribeTasks](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DescribeTasks.html) in the *Amazon Elastic Container Service API Reference*.
The following AWS Cloud Map actions are required to stop a task:
+ `servicediscovery:DeregisterInstance`
+ `servicediscovery:GetOperation`
If access to the shared namespace is revoked, tasks may remain in a `DEACTIVATING` or `DEPROVISIONING` state until namespace access is restored. Request the namespace owner to restore access to the namespace.