|
| 1 | +# AWS CloudMap Name Resolution |
| 2 | + |
| 3 | +This component uses [AWS Cloud Map](https://aws.amazon.com/cloud-map/) for service discovery in Dapr. It supports both HTTP and DNS namespaces, allowing services to discover and connect to other services using AWS Cloud Map's service discovery capabilities. |
| 4 | + |
| 5 | +## Component Format |
| 6 | + |
| 7 | +```yaml |
| 8 | +apiVersion: dapr.io/v1alpha1 |
| 9 | +kind: Configuration |
| 10 | +metadata: |
| 11 | + name: appconfig |
| 12 | +spec: |
| 13 | + nameResolution: |
| 14 | + component: "aws.cloudmap" |
| 15 | + configuration: |
| 16 | + # Required: AWS CloudMap namespace configuration (one of these is required) |
| 17 | + namespaceName: "my-namespace" # The name of your CloudMap namespace |
| 18 | + # namespaceId: "ns-xxxxxx" # Alternative: Use namespace ID instead of name |
| 19 | + |
| 20 | + # Optional: AWS authentication (choose one authentication method) |
| 21 | + # Option 1: Environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY |
| 22 | + # Option 2: IAM roles for Amazon EKS |
| 23 | + # Option 3: Explicit credentials (not recommended for production) |
| 24 | + accessKey: "****" |
| 25 | + secretKey: "****" |
| 26 | + sessionToken: "****" # Optional |
| 27 | + |
| 28 | + # Optional: AWS region and endpoint configuration |
| 29 | + region: "us-west-2" |
| 30 | + endpoint: "http://localhost:4566" # Optional: Custom endpoint for testing |
| 31 | + |
| 32 | + # Optional: Dapr configuration |
| 33 | + defaultDaprPort: 3500 # Default port for Dapr sidecar if not specified in instance attributes |
| 34 | +``` |
| 35 | +
|
| 36 | +## Specification |
| 37 | +
|
| 38 | +### AWS Authentication |
| 39 | +
|
| 40 | +The component supports multiple authentication methods: |
| 41 | +
|
| 42 | +1. Environment Variables: |
| 43 | + - AWS_ACCESS_KEY_ID |
| 44 | + - AWS_SECRET_ACCESS_KEY |
| 45 | + - AWS_SESSION_TOKEN (optional) |
| 46 | +
|
| 47 | +2. IAM Roles: |
| 48 | + - When running on AWS (EKS, EC2, etc.), the component can use IAM roles |
| 49 | +
|
| 50 | +3. Explicit Credentials: |
| 51 | + - Provided in the component metadata (not recommended for production) |
| 52 | +
|
| 53 | +### Required Permissions |
| 54 | +
|
| 55 | +The AWS credentials must have the following permissions: |
| 56 | +```json |
| 57 | +{ |
| 58 | + "Version": "2012-10-17", |
| 59 | + "Statement": [ |
| 60 | + { |
| 61 | + "Effect": "Allow", |
| 62 | + "Action": [ |
| 63 | + "servicediscovery:DiscoverInstances", |
| 64 | + "servicediscovery:GetNamespace", |
| 65 | + "servicediscovery:ListNamespaces" |
| 66 | + ], |
| 67 | + "Resource": "*" |
| 68 | + } |
| 69 | + ] |
| 70 | +} |
| 71 | +``` |
| 72 | + |
| 73 | +### Configuration Options |
| 74 | + |
| 75 | +| Property | Type | Required | Default | Description | |
| 76 | +|----------|------|----------|---------|-------------| |
| 77 | +| namespaceName | string | One of namespaceName or namespaceId | "" | The name of your AWS CloudMap namespace | |
| 78 | +| namespaceId | string | One of namespaceName or namespaceId | "" | The ID of your AWS CloudMap namespace | |
| 79 | +| region | string | N | "" | AWS region. If not provided, will be determined from environment or instance metadata | |
| 80 | +| endpoint | string | N | "" | Custom endpoint for AWS CloudMap API. Useful for testing with LocalStack | |
| 81 | +| defaultDaprPort | number | N | 3500 | Default port for Dapr sidecar if not specified in instance attributes | |
| 82 | + |
| 83 | +### Service Registration |
| 84 | + |
| 85 | +To use this name resolver, your services must be registered in AWS CloudMap. When registering instances, ensure they have the following attributes: |
| 86 | + |
| 87 | +1. Required: One of these address attributes: |
| 88 | + - `AWS_INSTANCE_IPV4`: IPv4 address of the instance |
| 89 | + - `AWS_INSTANCE_IPV6`: IPv6 address of the instance |
| 90 | + - `AWS_INSTANCE_CNAME`: Hostname of the instance |
| 91 | + |
| 92 | +2. Optional: Dapr sidecar port attribute: |
| 93 | + - `DAPR_PORT`: The port that the Dapr sidecar is listening on |
| 94 | + - If not specified, the component will use the `defaultDaprPort` from configuration (defaults to 3500) |
| 95 | + |
| 96 | +The resolver will only return healthy instances (those with `HEALTHY` status) to ensure reliable service communication. |
| 97 | + |
| 98 | +Example instance attributes: |
| 99 | +```json |
| 100 | +{ |
| 101 | + "AWS_INSTANCE_IPV4": "10.0.0.1", |
| 102 | + "DAPR_PORT": "50002" |
| 103 | +} |
| 104 | +``` |
| 105 | + |
| 106 | + |
| 107 | +## Example Usage |
| 108 | + |
| 109 | +### Minimal Configuration |
| 110 | + |
| 111 | +```yaml |
| 112 | +apiVersion: dapr.io/v1alpha1 |
| 113 | +kind: Configuration |
| 114 | +metadata: |
| 115 | + name: appconfig |
| 116 | +spec: |
| 117 | + nameResolution: |
| 118 | + component: "aws.cloudmap" |
| 119 | + configuration: |
| 120 | + namespaceName: "mynamespace.dev" |
| 121 | + defaultDaprPort: 50002 |
| 122 | +``` |
| 123 | +
|
| 124 | +### Local Development with LocalStack |
| 125 | +
|
| 126 | +```yaml |
| 127 | +apiVersion: dapr.io/v1alpha1 |
| 128 | +kind: Configuration |
| 129 | +metadata: |
| 130 | + name: appconfig |
| 131 | +spec: |
| 132 | + nameResolution: |
| 133 | + component: "aws.cloudmap" |
| 134 | + configuration: |
| 135 | + namespaceName: "my-namespace" |
| 136 | + region: "us-east-1" |
| 137 | + endpoint: "http://localhost:4566" |
| 138 | + accessKey: "test" |
| 139 | + secretKey: "test" |
| 140 | +``` |
0 commit comments