Name resolution provider component specs

• 1: AWS Cloudmap
• 2: HashiCorp Consul
• 3: Kubernetes DNS
• 4: mDNS
• 5: Nameformat
• 6: SQLite

1 - AWS Cloudmap

This component uses AWS 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.

Configuration format

Name resolution is configured via the Dapr Configuration.

Within the configuration YAML, set the spec.nameResolution.component property to "aws.cloudmap", then pass configuration options in the spec.nameResolution.configuration dictionary.

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
  name: appconfig
spec:
  nameResolution:
    component: "aws.cloudmap"
    version: "v1"
    configuration:
      # Required: AWS CloudMap namespace configuration (one of these is required)
      namespaceName: "my-namespace"  # The name of your CloudMap namespace
      # namespaceId: "ns-xxxxxx"    # Alternative: Use namespace ID instead of name

      # Optional: AWS authentication (choose one authentication method)
      # Option 1: Environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
      # Option 2: IAM roles for Amazon EKS
      # Option 3: Explicit credentials (not recommended for production)
      accessKey: "****"
      secretKey: "****"
      sessionToken: "****"  # Optional

      # Optional: AWS region and endpoint configuration
      region: "us-west-2"
      endpoint: "http://localhost:4566"  # Optional: Custom endpoint for testing

      # Optional: Dapr configuration
      defaultDaprPort: 50002  # Default port for Dapr sidecar if not specified in instance attributes

Specification

AWS authentication

The component supports multiple authentication methods:

1. Environment Variables:

   • AWS_ACCESS_KEY_ID
   • AWS_SECRET_ACCESS_KEY
   • AWS_SESSION_TOKEN (optional)

2. IAM Roles:

   • When running on AWS (EKS, EC2, etc.), the component can use IAM roles

3. Explicit Credentials:

   • Provided in the component metadata (not recommended for production)

Required permissions

The AWS credentials must have the following permissions:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "servicediscovery:DiscoverInstances",
                "servicediscovery:GetNamespace",
                "servicediscovery:ListNamespaces"
            ],
            "Resource": "*"
        }
    ]
}

Spec configuration fields

Service registration

To use this name resolver, your services must be registered in AWS CloudMap. When registering instances, ensure they have the following attributes:

1. Required: One of these address attributes:

   • AWS_INSTANCE_IPV4: IPv4 address of the instance
   • AWS_INSTANCE_IPV6: IPv6 address of the instance
   • AWS_INSTANCE_CNAME: Hostname of the instance

2. Optional: Dapr sidecar port attribute:

   • DAPR_PORT: The port that the Dapr sidecar is listening on
   • If not specified, the component will use the defaultDaprPort from configuration (defaults to 3500)

The resolver only returns healthy instances (those with HEALTHY status) to ensure reliable service communication.

Example instance attributes:

{
    "AWS_INSTANCE_IPV4": "10.0.0.1",
    "DAPR_PORT": "50002"
}

Example Usage

Name resolution is configured via the Dapr Configuration. Here are some examples of its usage.

Minimal Configuration

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
  name: appconfig
spec:
  nameResolution:
    component: "aws.cloudmap"
    configuration:
      namespaceName: "mynamespace.dev"
      defaultDaprPort: 50002

Local Development with LocalStack

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
  name: appconfig
spec:
  nameResolution:
    component: "aws.cloudmap"
    configuration:
      namespaceName: "my-namespace"
      region: "us-east-1"
      endpoint: "http://localhost:4566"
      accessKey: "test"
      secretKey: "test"

Related Links

• Service invocation building block
• AWS Cloudmap documentation

2 - HashiCorp Consul

Configuration format

Hashicorp Consul is setup within the Dapr Configuration.

Within the config, add a nameResolution spec and set the component field to "consul".

If you are using the Dapr sidecar to register your service to Consul then you will need the following configuration:

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
  name: appconfig
spec:
  nameResolution:
    component: "consul"
    configuration:
      selfRegister: true

If Consul service registration is managed externally from Dapr you need to ensure that the Dapr-to-Dapr internal gRPC port is added to the service metadata under DAPR_PORT (this key is configurable) and that the Consul service Id matches the Dapr app Id. You can then omit selfRegister from the config above.

Behaviour

On init the Consul component either validates the connection to the configured (or default) agent or registers the service if configured to do so. The name resolution interface does not cater for an “on shutdown” pattern so consider this when using Dapr to register services to Consul as it does not deregister services.

The component resolves target apps by filtering healthy services and looks for a DAPR_PORT in the metadata (key is configurable) in order to retrieve the Dapr sidecar port. Consul service.meta is used over service.port so as to not interfere with existing Consul estates.

Spec configuration fields

The configuration spec is fixed to v1.3.0 of the Consul API

Sample configurations

Basic

The minimum configuration needed is the following:

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
  name: appconfig
spec:
  nameResolution:
    component: "consul"

Registration with additional customizations

Enabling SelfRegister it is then possible to customize the checks, tags and meta

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
  name: appconfig
spec:
  nameResolution:
    component: "consul"
    configuration:
      client:
        address: "127.0.0.1:8500"
      selfRegister: true
      checks:
        - name: "Dapr Health Status"
          checkID: "daprHealth:${APP_ID}"
          interval: "15s"
          http: "http://${HOST_ADDRESS}:${DAPR_HTTP_PORT}/v1.0/healthz"
        - name: "Service Health Status"
          checkID: "serviceHealth:${APP_ID}"
          interval: "15s"
          http: "http://${HOST_ADDRESS}:${APP_PORT}/health"
      tags:
        - "dapr"
        - "v1"
        - "${OTHER_ENV_VARIABLE}"
      meta:
        DAPR_METRICS_PORT: "${DAPR_METRICS_PORT}"
        DAPR_PROFILE_PORT: "${DAPR_PROFILE_PORT}"
      daprPortMetaKey: "DAPR_PORT"
      queryOptions:
        useCache: true
        filter: "Checks.ServiceTags contains dapr"

Advanced registration

Configuring the advanced registration gives you full control over setting all the Consul properties possible when registering.

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
  name: appconfig
spec:
  nameResolution:
    component: "consul"
    configuration:
      client:
          address: "127.0.0.1:8500"
      selfRegister: false
      queryOptions:
        useCache: true
      daprPortMetaKey: "DAPR_PORT"
      advancedRegistration:
        name: "${APP_ID}"
        port: ${APP_PORT}
        address: "${HOST_ADDRESS}"
        check:
          name: "Dapr Health Status"
          checkID: "daprHealth:${APP_ID}"
          interval: "15s"
          http: "http://${HOST_ADDRESS}:${DAPR_HTTP_PORT}/v1.0/healthz"
        meta:
          DAPR_METRICS_PORT: "${DAPR_METRICS_PORT}"
          DAPR_PROFILE_PORT: "${DAPR_PROFILE_PORT}"
        tags:
          - "dapr"

Setup HashiCorp Consul

• Self-Hosted
• Kubernetes

Related links

• Service invocation building block

3 - Kubernetes DNS

Configuration format

Generally, Kubernetes DNS name resolution is configured automatically in Kubernetes mode by Dapr. There is no configuration needed to use Kubernetes DNS as your name resolution provider unless some overrides are necessary for the Kubernetes name resolution component.

In the scenario that an override is required, within a Dapr Configuration CRD, add a nameResolution spec and set the component field to "kubernetes". The other configuration fields can be set as needed in a configuration map, as seen below.

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
  name: appconfig
spec:
  nameResolution:
    component: "kubernetes"
    configuration:
      clusterDomain: "cluster.local"  # Mutually exclusive with the template field
      template: "{{.ID}}-{{.Data.region}}.internal:{{.Port}}" # Mutually exclusive with the clusterDomain field

Behaviour

The component resolves target apps by using the Kubernetes cluster’s DNS provider. You can learn more in the Kubernetes docs.

Spec configuration fields

The configuration spec is fixed to v1.3.0 of the Consul API

Related links

• Service invocation building block
• Kubernetes DNS docs

4 - mDNS

Configuration format

Multicast DNS (mDNS) is configured automatically in self-hosted mode by Dapr. There is no configuration needed to use mDNS as your name resolution provider.

Behaviour

The component resolves target apps by using the host system’s mDNS service. You can learn more about mDNS here.

Troubleshooting

In some cloud provider virtual networks, such as Microsoft Azure, mDNS is not available. Use an alternate provider such as HashiCorp Consul instead.

On some enterprise-managed systems, mDNS may be disabled on macOS if a network filter/proxy is configured. Check with your IT department if mDNS is disabled and you are unable to use service invocation locally.

Spec configuration fields

Not applicable, as mDNS is configured by Dapr when running in self-hosted mode.

Related links

• Service invocation building block
• mDNS reference

5 - Nameformat

The Name Format name resolver provides a flexible way to resolve service names using a configurable format string with placeholders. This is useful in scenarios where you want to map service names to predictable DNS names following a specific pattern.

Consider using this name resolver if there is no specific name resolver available for your service registry, but your service registry can expose services via internal DNS names using predictable naming conventions.

Configuration Format

Name resolution is configured via the Dapr Configuration.

Within the configuration YAML, set the spec.nameResolution.component property to "nameformat", then pass configuration options in the spec.nameResolution.configuration dictionary.

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
  name: appconfig
spec:
  nameResolution:
    component: "nameformat"
    configuration:
      format: "service-{appid}.default.svc.cluster.local"  # Replace with your desired format pattern

Spec configuration fields

Examples

When configured with format: "service-{appid}.default.svc.cluster.local", the resolver transforms service names as follows:

• Service ID “myapp” → “service-myapp.default.svc.cluster.local”
• Service ID “frontend” → “service-frontend.default.svc.cluster.local”

Notes

• Empty service IDs are not allowed and results in an error.
• The format string must be provided in the configuration
• The format string must contain at least one {appid} placeholder

6 - SQLite

As an alternative to mDNS, the SQLite name resolution component can be used for running Dapr on single-node environments and for local development scenarios. Dapr sidecars that are part of the cluster store their information in a SQLite database on the local machine.

Configuration format

Name resolution is configured via the Dapr Configuration.

Within the Configuration YAML, set the spec.nameResolution.component property to "sqlite", then pass configuration options in the spec.nameResolution.configuration dictionary.

This is the basic example of a Configuration resource:

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
  name: appconfig
spec:
  nameResolution:
    component: "sqlite"
    version: "v1"
    configuration:
      connectionString: "/home/user/.dapr/nr.db"

Spec configuration fields

When using the SQLite name resolver component, the spec.nameResolution.configuration dictionary contains these options:

Related links

• Service invocation building block