This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

名称解析提供程序组件规范

支持的名称解析提供程序以启用 Dapr 服务调用

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

以下组件为服务调用构建块提供名称解析。

名称解析组件通过配置进行配置。

Table headers to note:

Header	Description	Example
Status	Component certification status	Alpha Beta Stable
Component version	The version of the component	v1
Since runtime version	The version of the Dapr runtime when the component status was set or updated	1.11

Generic

Component	Status	Component version	Since runtime version
HashiCorp Consul	Alpha	v1	1.2
NameFormat	Alpha	v1	1.16
SQLite	Alpha	v1	1.13

Kubernetes

Component	Status	Component version	Since runtime version
Kubernetes	Stable	v1	1.0

Self-Hosted

Component	Status	Component version	Since runtime version
mDNS	Stable	v1	1.0

1 - AWS Cloudmap

AWS Cloudmap 名称解析组件的详细信息

该组件使用 AWS Cloud Map 在 Dapr 中进行服务发现。它支持 HTTP 和 DNS 命名空间，允许服务使用 AWS Cloud Map 的服务发现能力来发现并连接到其他服务。

配置格式

名称解析通过 Dapr Configuration 进行配置。

在配置 YAML 中，将 spec.nameResolution.component 属性设置为 "aws.cloudmap"，然后在 spec.nameResolution.configuration 字典中传递配置选项。

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

规范说明

AWS 身份验证

该组件支持多种身份验证方法：

环境变量：
- AWS_ACCESS_KEY_ID
- AWS_SECRET_ACCESS_KEY
- AWS_SESSION_TOKEN（可选）
IAM 角色：
- 在 AWS（EKS、EC2 等）上运行时，组件可以使用 IAM 角色
显式凭证：
- 在组件元数据中提供（不推荐在生产环境中使用）

所需权限

AWS 凭证必须具有以下权限：

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

规范配置字段

字段	是否必需	类型	默认值	描述
namespaceName	namespaceName 或 namespaceId 其中之一	string	""	AWS CloudMap 命名空间的名称
namespaceId	namespaceName 或 namespaceId 其中之一	string	""	AWS CloudMap 命名空间的 ID
region	N	string	""	AWS 区域。如果未提供，将从环境或实例元数据中确定
endpoint	N	string	""	AWS Cloud Map API 的自定义端点。适用于使用 LocalStack 进行测试
defaultDaprPort	N	number	3500	如果在实例属性中未指定，则为 Dapr 边车的默认端口

服务注册

要使用此名称解析器，您的服务必须在 AWS Cloud Map 中注册。注册实例时，确保它们具有以下属性：

必需：以下地址属性之一：
- AWS_INSTANCE_IPV4：实例的 IPv4 地址
- AWS_INSTANCE_IPV6：实例的 IPv6 地址
- AWS_INSTANCE_CNAME：实例的主机名
可选：Dapr 边车端口属性：
- DAPR_PORT：Dapr 边车正在监听的端口
- 如果未指定，组件将使用配置中的 defaultDaprPort（默认为 3500）

解析器仅返回健康的实例（具有 HEALTHY 状态的实例）以确保可靠的服务通信。

示例实例属性：

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

使用示例

名称解析通过 Dapr Configuration 进行配置。以下是一些使用示例。

最小配置

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

使用 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"

2 - HashiCorp Consul

HashiCorp Consul 名称解析组件的详细信息

配置格式

HashiCorp Consul 在 Dapr 配置中进行设置。

在配置中，添加 nameResolution 规范并将 component 字段设置为 "consul"。

如果您使用 Dapr 边车将服务注册到 Consul，则需要以下配置：

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

如果 Consul 服务注册由 Dapr 外部管理，您需要确保 Dapr 到 Dapr 的内部 gRPC 端口已添加到服务元数据中的 DAPR_PORT 下（此键可配置），并且 Consul 服务 ID 与 Dapr 应用 ID 匹配。然后您可以省略上述配置中的 selfRegister。

行为

在 init 时，Consul 组件会验证与已配置（或默认）代理的连接，或者如果配置为注册服务则注册服务。名称解析接口不支持"关闭时"模式，因此在使用 Dapr 将服务注册到 Consul 时请考虑这一点，因为它不会注销服务。

该组件通过过滤健康服务来解析目标应用，并在元数据中查找 DAPR_PORT（键可配置）以获取 Dapr 边车端口。使用 Consul service.meta 而不是 service.port，以免干扰现有的 Consul 环境。

规范配置字段

配置规范固定为 Consul API 的 v1.3.0 版本

字段	必填	类型	详情	示例
Client	N	*api.Config	配置与 Consul 代理的客户端连接。如果为空，它将使用 sdk 默认值，在这种情况下只是地址 `127.0.0.1:8500`	`10.0.4.4:8500`
QueryOptions	N	*api.QueryOptions	配置用于解析健康服务的查询，如果为空，它将默认为 `UseCache:true`	`UseCache: false`, `Datacenter: "myDC"`
Checks	N	[]*api.AgentServiceCheck	配置注册时的健康检查。如果为空，它将默认为对 Dapr 边车健康端点的单个健康检查	参见示例配置
Tags	N	`[]string`	配置注册服务时要包含的任何标签	`- "dapr"`
Meta	N	`map[string]string`	配置注册服务时要包含的任何其他元数据	`DAPR_METRICS_PORT: "${DAPR_METRICS_PORT}"`
DaprPortMetaKey	N	`string`	用于在服务解析期间从 Consul 服务元数据获取 Dapr 边车端口的键，它也将在注册期间用于在元数据中设置 Dapr 边车端口。如果为空，它将默认为 `DAPR_PORT`	`"DAPR_TO_DAPR_PORT"`
SelfRegister	N	`bool`	控制 Dapr 是否将服务注册到 Consul。名称解析接口不支持"关闭时"模式，因此如果使用 Dapr 将服务注册到 Consul，请考虑这一点，因为它不会注销服务。如果为空，它将默认为 `false`	`true`
AdvancedRegistration	N	*api.AgentServiceRegistration	通过配置完全控制服务注册。如果配置了该组件，它将忽略任何 Checks、Tags、Meta 和 SelfRegister 的配置。	参见示例配置

示例配置

基本配置

所需的最小配置如下：

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

带有其他自定义的注册

启用 SelfRegister 后，可以自定义检查、标签和元数据

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"

高级注册

配置高级注册使您能够完全控制在注册时设置所有可能的 Consul 属性。

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"

设置 HashiCorp Consul

HashiCorp 提供了有关如何为不同托管模型设置 Consul 的深入指南。查看自托管指南

HashiCorp 提供了有关如何为不同托管模型设置 Consul 的深入指南。查看 Kubernetes 指南

3 - Kubernetes DNS

Kubernetes DNS 名称解析组件的详细信息

配置格式

通常，Dapr 会在 Kubernetes 模式下自动配置 Kubernetes DNS 名称解析。除非需要对 Kubernetes 名称解析组件进行某些覆盖，否则无需额外配置即可将 Kubernetes DNS 用作名称解析提供程序。

如果需要覆盖，可以在 Dapr 配置 CRD 中添加 nameResolution 规范，并将 component 字段设置为 "kubernetes"。其他配置字段可以在 configuration 映射中按需设置，如下所示。

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
  name: appconfig
spec:
  nameResolution:
    component: "kubernetes"
    configuration:
      clusterDomain: "cluster.local"  # 与 template 字段互斥
      template: "{{.ID}}-{{.Data.region}}.internal:{{.Port}}" # 与 clusterDomain 字段互斥

行为

该组件使用 Kubernetes 集群的 DNS 提供程序来解析目标应用程序。你可以在 Kubernetes 文档中了解更多信息。

规范配置字段

配置规范固定为 Consul API 的 v1.3.0 版本

字段	必填	类型	详情	示例
clusterDomain	N	`string`	用于解析地址的集群域。此字段与 `template` 字段互斥。	`cluster.local`
template	N	`string`	使用 text/template 解析地址时要解析的模板字符串。该模板将由 ResolveRequest 结构体中的字段填充。此字段与 `clusterDomain` 字段互斥。	`{{.ID}}-{{.Data.region}}.{{.Namespace}}.internal:{{.Port}}`

4 - mDNS

关于 mDNS 名称解析组件的详细信息

配置格式

组播 DNS（mDNS）在自托管模式中由 Dapr 自动配置。无需配置即可使用 mDNS 作为您的名称解析提供程序。

行为

该组件通过使用主机系统的 mDNS 服务来解析目标应用程序。您可以在此处了解更多关于 mDNS 的信息。

故障排除

在某些云提供商的虚拟网络中，例如 Microsoft Azure，mDNS 不可用。请改用其他提供程序，例如 HashiCorp Consul。

在某些企业管理的系统上，如果配置了网络过滤器/代理，macOS 上的 mDNS 可能会被禁用。如果 mDNS 被禁用且您无法在本地使用服务调用，请联系您的 IT 部门。

规范配置字段

不适用，因为在自托管模式下运行时，mDNS 由 Dapr 配置。

5 - Nameformat

NameFormat 名称解析组件的详细信息

名称格式名称解析器提供了一种使用带有占位符的可配置格式字符串来解析服务名称的灵活方式。这在需要将服务名称映射为遵循特定模式的可预测 DNS 名称的场景中非常有用。

如果您的服务注册表没有专用的名称解析器，但可以通过可预测的命名约定通过内部 DNS 名称公开服务，请考虑使用此名称解析器。

配置格式

名称解析通过 Dapr Configuration 进行配置。

在配置 YAML 中，将 spec.nameResolution.component 属性设置为 "nameformat"，然后在 spec.nameResolution.configuration 字典中传递配置选项。

apiVersion: dapr.io/v1alpha1
kind: Configuration
metadata:
  name: appconfig
spec:
  nameResolution:
    component: "nameformat"
    configuration:
      format: "service-{appid}.default.svc.cluster.local"  # 替换为所需的格式模式

规格配置字段

字段	必填	详情	示例
format	Y	用于名称解析的格式字符串。必须包含 `{appid}` 占位符，该占位符将被替换为实际的服务名称。	`"service-{appid}.default.svc.cluster.local"`

示例

配置为 format: "service-{appid}.default.svc.cluster.local" 时，解析器会将服务名称转换如下：

服务 ID “myapp” → “service-myapp.default.svc.cluster.local”
服务 ID “frontend” → “service-frontend.default.svc.cluster.local”

注意事项

不允许使用空服务 ID，否则会导致错误。
必须在配置中提供格式字符串
格式字符串必须至少包含一个 {appid} 占位符

6 - SQLite

SQLite 名称解析组件的详细信息

作为 mDNS 的替代方案，SQLite 名称解析组件可用于在单节点环境和本地开发场景中运行 Dapr。属于集群一部分的 Dapr 边车将其信息存储在本地机器上的 SQLite 数据库中。

注意

此组件已针对所有 Dapr 实例在同一台物理机上运行的场景进行了优化，数据库通过同一本地挂载磁盘访问。在通过网络（包括 SMB/NFS）访问的数据库文件上使用 SQLite nameresolver 可能会导致数据损坏等问题，并且不受支持。

配置格式

名称解析通过 Dapr Configuration 进行配置。

在 Configuration YAML 中，将 spec.nameResolution.component 属性设置为 "sqlite"，然后在 spec.nameResolution.configuration 字典中传递配置选项。

这是 Configuration 资源的基本示例：

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

Spec 配置字段

使用 SQLite 名称解析器组件时，spec.nameResolution.configuration 字典包含以下选项：

字段	必填	类型	详情	示例
`connectionString`	Y	`string`	SQLite 数据库的连接字符串。通常，这是磁盘上文件的路径，相对于当前工作目录，或绝对路径。	`"nr.db"`（相对于工作目录），`"/home/user/.dapr/nr.db"`
`updateInterval`	N	Go duration（作为 `string`）	活跃的 Dapr 边车更新其在数据库中的状态的间隔，该状态用作健康检查。较小的间隔可降低应用程序离线时返回陈旧数据的可能性，但会增加数据库的负载。必须至少比 `timeout` 大 1s。带小数秒的值会被截断（例如，`1500ms` 变为 `1s`）。默认值：`5s`	`"2s"`
`timeout`	N	Go duration（作为 `string`）。必须至少为 1s。	数据库操作的超时时间。整数被解释为秒数。默认值为 `1s`	`"2s"`，`2`
`tableName`	N	`string`	存储数据的表的名称。如果表不存在，则由 Dapr 创建该表。默认值为 `hosts`。	`"hosts"`
`metadataTableName`	N	`string`	Dapr 用于存储组件元数据的表的名称。如果表不存在，则由 Dapr 创建该表。默认值为 `metadata`。	`"metadata"`
`cleanupInterval`	N	Go duration（作为 `string`）	从数据库中删除陈旧记录的间隔。默认值：`1h`（1 小时）	`"10m"`
`busyTimeout`	N	Go duration（作为 `string`）	在 SQLite 数据库当前正忙于服务另一个请求时，在返回"数据库繁忙"错误之前等待的间隔。这是一个高级设置。 `busyTimeout` 控制锁定在 SQLite 中如何工作。对于 SQLite，写入是独占的，因此每次任何应用程序写入时数据库都会被锁定。如果另一个应用程序尝试写入，它会等待最多 `busyTimeout`，然后返回"数据库繁忙"错误。但是 `timeout` 设置控制整个操作的超时时间。例如，如果查询在数据库获取锁定后"挂起"（因此繁忙超时被清除），那么 `timeout` 生效。默认值：`800ms`（800 毫秒）	`"100ms"`
`disableWAL`	N	`bool`	如果设置为 true，则禁用 SQLite 数据库日志记录的预写日志记录。这仅适用于高级场景	`true`，`false`

名称解析提供程序组件规范

Generic

Kubernetes

Self-Hosted

1 - AWS Cloudmap

配置格式

规范说明

AWS 身份验证

所需权限

规范配置字段

服务注册

使用示例

最小配置

使用 LocalStack 进行本地开发

相关链接

2 - HashiCorp Consul

配置格式

行为

规范配置字段

示例配置

基本配置

带有其他自定义的注册

高级注册

设置 HashiCorp Consul

相关链接

3 - Kubernetes DNS

配置格式

行为

规范配置字段

相关链接

4 - mDNS

配置格式

行为

故障排除

规范配置字段

相关链接

5 - Nameformat

配置格式

规格配置字段

示例

注意事项

6 - SQLite

注意

配置格式

Spec 配置字段

相关链接