HashiCorp Consul name resolution provider spec

Detailed information on the HashiCorp Consul name resolution component

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:

  1. apiVersion: dapr.io/v1alpha1
  2. kind: Configuration
  3. metadata:
  4. name: appconfig
  5. spec:
  6. nameResolution:
  7. component: "consul"
  8. configuration:
  9. 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

FieldRequiredTypeDetailsExamples
ClientNapi.ConfigConfigures client connection to the Consul agent. If blank it will use the sdk defaults, which in this case is just an address of 127.0.0.1:850010.0.4.4:8500
QueryOptionsNapi.QueryOptionsConfigures query used for resolving healthy services, if blank it will default to UseCache:trueUseCache: false, Datacenter: “myDC”
ChecksN[]api.AgentServiceCheckConfigures health checks if/when registering. If blank it will default to a single health check on the Dapr sidecar health endpointSee sample configs
TagsN[]stringConfigures any tags to include if/when registering services- “dapr”
MetaNmap[string]stringConfigures any additional metadata to include if/when registering servicesDAPR_METRICS_PORT: “${DAPR_METRICS_PORT}”
DaprPortMetaKeyNstringThe key used for getting the Dapr sidecar port from Consul service metadata during service resolution, it will also be used to set the Dapr sidecar port in metadata during registration. If blank it will default to DAPR_PORT“DAPR_TO_DAPR_PORT”
SelfRegisterNboolControls if Dapr will register the service to Consul. The name resolution interface does not cater for an “on shutdown” pattern so please consider this if using Dapr to register services to Consul as it will not deregister services. If blank it will default to falsetrue
AdvancedRegistrationNapi.AgentServiceRegistrationGives full control of service registration through configuration. If configured the component will ignore any configuration of Checks, Tags, Meta and SelfRegister.See sample configs

Sample configurations

Basic

The minimum configuration needed is the following:

  1. apiVersion: dapr.io/v1alpha1
  2. kind: Configuration
  3. metadata:
  4. name: appconfig
  5. spec:
  6. nameResolution:
  7. component: "consul"

Registration with additional customizations

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

  1. apiVersion: dapr.io/v1alpha1
  2. kind: Configuration
  3. metadata:
  4. name: appconfig
  5. spec:
  6. nameResolution:
  7. component: "consul"
  8. configuration:
  9. client:
  10. address: "127.0.0.1:8500"
  11. selfRegister: true
  12. checks:
  13. - name: "Dapr Health Status"
  14. checkID: "daprHealth:${APP_ID}"
  15. interval: "15s"
  16. http: "http://${HOST_ADDRESS}:${DAPR_HTTP_PORT}/v1.0/healthz"
  17. - name: "Service Health Status"
  18. checkID: "serviceHealth:${APP_ID}"
  19. interval: "15s"
  20. http: "http://${HOST_ADDRESS}:${APP_PORT}/health"
  21. tags:
  22. - "dapr"
  23. - "v1"
  24. - "${OTHER_ENV_VARIABLE}"
  25. meta:
  26. DAPR_METRICS_PORT: "${DAPR_METRICS_PORT}"
  27. DAPR_PROFILE_PORT: "${DAPR_PROFILE_PORT}"
  28. daprPortMetaKey: "DAPR_PORT"
  29. queryOptions:
  30. useCache: true
  31. filter: "Checks.ServiceTags contains dapr"

Advanced registration

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

  1. apiVersion: dapr.io/v1alpha1
  2. kind: Configuration
  3. metadata:
  4. name: appconfig
  5. spec:
  6. nameResolution:
  7. component: "consul"
  8. configuration:
  9. client:
  10. address: "127.0.0.1:8500"
  11. selfRegister: false
  12. queryOptions:
  13. useCache: true
  14. daprPortMetaKey: "DAPR_PORT"
  15. advancedRegistration:
  16. name: "${APP_ID}"
  17. port: ${APP_PORT}
  18. address: "${HOST_ADDRESS}"
  19. check:
  20. name: "Dapr Health Status"
  21. checkID: "daprHealth:${APP_ID}"
  22. interval: "15s"
  23. http: "http://${HOST_ADDRESS}:${DAPR_HTTP_PORT}/v1.0/healthz"
  24. meta:
  25. DAPR_METRICS_PORT: "${DAPR_METRICS_PORT}"
  26. DAPR_PROFILE_PORT: "${DAPR_PROFILE_PORT}"
  27. tags:
  28. - "dapr"

Setup HashiCorp Consul

HashiCorp offer in depth guides on how to setup Consul for different hosting models. Check out the self-hosted guide here

HashiCorp offer in depth guides on how to setup Consul for different hosting models. Check out the Kubernetes guide here

Last modified October 12, 2023: Update config.toml (#3826) (0ffc2e7)