Registration CRD configuration reference

This topic provides reference information for Registration custom resource definitions (CRDs). You can use this CRD to register an external service with Consul on Kubernetes. For more information. Refer to Register services running on external nodes to Consul on Kubernetes for more information.

Configuration model

The following list outlines field hierarchy, language-specific data types, and requirements in a Registration CRD. Click on a property name to view additional details, including default values.

• apiVersion: string | required | must be set to consul.hashicorp.com/v1alpha1
• kind: string | required | must be set to Registration
• metadata: map
  • name: string
• spec: map | required
  • address: string
  • check: map
    • checkId: string
    • definition: map
      • body: string
      • deregisterCriticalServiceAfterDuration: string
      • grpc: string
      • grpcUseTLS: boolean | false
      • header: map of strings
      • http: string
      • intervalDuration: string
      • method: string
      • osService: string
      • tcp: string
      • tcpUseTLS: boolean
      • timeoutDuration: string
      • tlsServerName: string
      • tlsSkipVerify: boolean | false
      • udp: string
    • exposedPort: integer
    • name: string
    • namespace: string EnterpriseEnterprise
    • node: string
    • notes: string
    • output: string
    • partition: string EnterpriseEnterprise
    • serviceId: string
    • serviceName: string
    • status: string
    • type: string
  • datacenter: string
  • id: string
  • locality: map
    • region: string
    • zone: string
  • node: string
  • nodeMeta: map of strings
  • partition: string EnterpriseEnterprise
  • service: map
    • address: string
    • enableTagOverride: boolean | false
    • id: string
    • locality: map
      • region: string
      • zone: string
    • meta: map of strings
    • name: string
    • namespace: string EnterpriseEnterprise
    • partition: string EnterpriseEnterprise
    • port: integer
    • socketPath: string
    • taggedAddresses: map
      • address: string
      • port: integer
    • tags: map of strings
    • weights: map
      • passing: integer | 1
      • warning: integer | 1
  • skipNodeUpdate: boolean | false
  • taggedAddresses: map of strings

Complete configuration

When every field is defined, a Registration CRD has the following form:

apiVersion: consul.hashicorp.com/v1alpha1         # required
kind: Registration                                # required
metadata:
  name: <groupName>
spec:
  address: 10.0.0.1
  check:
    name: external-health-check
    checkId:  unique-id
    definition:  
      body: "{\"custom\": \"json\"}"
      deregisterCriticalServiceAfterDuration: false
      grpc: 127.0.0.1:443
      grpcUseTLS: false
      header:
        name: <http-header-name>
      intervalDuration: "5s"
      method: "GET"
      osService: <service-name>
      tcp: 127.0.0.1:4242
      tcpUseTLS: false
      timeoutDuration: 10s
      tlsServerName: <server-name>
      tlsSkipVerify: false
      udp: 127.0.0.1:80
    exposedPort: 200
    namespace: default
    notes: "Human readable description"
    output: "Human readable output"
    partition: default
    serviceId: <unique-service-ID>
    serviceName: <service-name>
    status: critical
    type: HTTP
  datacenter: dc1
  id: <unique-node-identifier>
  locality:
    region: us-east-1
    zone: us-east-1a
  node: <node-name>
  nodeMeta:
    - key: value
  partition: default
  service:
    address: "10.0.0.1:8300"
    enableTagOverride: false
    id: <unique-id>
    locality:
      region: us-east-1
      zone: us-east-1a
    meta:
      key: value
    name: <service-name>
    namespace: default
    partition: default
    port: 5400
    socketPath: /folder/socket
    taggedAddresses:
      lan: 
        address: 127.0.1.0 
        port: 80
    tags: 
      - "v2" 
      - "primary"
    weights:
      passing: 1
      warning: 1
  skipNodeUpdate: false
  taggedAddresses:
    lan: "192.168.10.10"

Specification

This section provides details about the fields you can configure in the Registration CRD.

apiVersion

Specifies the version of the Consul API for integrating with Kubernetes. The value must be consul.hashicorp.com/v1alpha1.

Values

• Default: None
• This field is required.
• String value that must be set to consul.hashicorp.com/v1alpha1.

kind

Specifies the type of configuration entry to implement. Must be set to Registration.

Values

• Default: None
• This field is required.
• Data type: String value that must be set to Registration.

metadata

Map that contains an arbitrary name for the configuration entry and the namespace it applies to.

Values

• Default: None
• Data type: Map

metadata.name

Specifies a name for the configuration entry that is used to identify the sameness group. To ensure consistency, use descriptive names and make sure that the same name is used when creating configuration entries to add each member to the sameness group.

Values

• Default: None
• This field is required.
• Data type: String

spec

Map that contains the details about the Registration CRD. The apiVersion, kind, and metadata fields are siblings of the spec field. All other configurations are children.

Values

• Default: None
• This field is required.
• Data type: Map

spec.address

Specifies the IP address where the external service is available.

Values

• Default: None
• Data type: String

spec.check

Specifies details for a health check. Health checks perform several safety functions, such as allowing a web balancer to gracefully remove failing nodes and allowing a database to replace a failed secondary. You can configure health checks to monitor the health of the entire node.

For more information about configuring health checks for Consul, refer to health check configuration reference.

Values

• Default: None
• Data type: Map

spec.check.checkId

Specifies an ID for the health check. When name values conflict, provide a unique identifier to avoid overwriting existing checks.

Values

• Default: None
• Data type: String

spec.check.definition

Specifies additional configuration details for the health check.

Requires child parameters deregisterCriticalServiceAfterDuration, intervalDuration, and timeoutDuration.

Values

• Default: None
• Data type: Map that can contain the following parameters:

spec.check.exposedPort

Specifies the port the service exposes to health checks.

Values

• Default: None
• Data type: Integer

spec.check.name

Specifies a name for the health check. Defaults to spec.service.id.

Values

• Default: None
• Data type: String

spec.check.namespace EnterpriseEnterprise

Specifies the Consul namespace the health check applies to. Refer to namespaces for more information.

Values

• Default: None
• Data type: String

spec.check.node

Specifies the name of the node the health check applies to.

Values

• Default: None
• Data type: String

spec.check.notes

Provides a human-readable description of the health check. The contents are not visible to Consul.

Values

• Default: None
• Data type: String

spec.check.output

Specifies human readable output in response to a health check.

Values

• Default: None
• Data type: String

spec.check.partition EnterpriseEnterprise

Specifies the Consul admin partition the health check applies to. Refer to admin partitions for more information.

Values

• Default: None
• Data type: String

spec.check.serviceId

Specifies the ID of the service to perform the health check on.

Values

• Default: None
• Data type: String

spec.check.serviceName

Specifies the name of the service to perform the health check on.

Values

• Default: None
• Data type: String

spec.check.status

Specifies the initial status of the health check. The default value for this field is critical, which requires services to pass a health check before making them available for service disocvery. You can specify one the following values:

• critical
• warning
• passing

Values

• Default: critical
• Data type: String

spec.check.type

Specifies the type health check in the form of a Kubernetes probe.

Values

• Default: None
• Data type: String

spec.datacenter

Specifies the datacenter to register the service's node in, which defaults to the agent's datacenter if not provided.

Values

• Default: None
• Data type: String

spec.id

Specifies a unique ID for the node to register. This optional ID must be a 36-character UUID-formatted string.

Values

• Default: None
• Data type: String

spec.locality

Specifies the cloud region and zone where the node is available.

Values

• Default: None
• Data type: Map that can contain the following parameters:

spec.node

Specifies the name of the node to register.

Values

• Default: None
• Data type: String

spec.nodeMeta

Specifies arbitrary KV metadata pairs for filtering purposes.

Values

• Default: None
• Data type: Map of strings

spec.partition EnterpriseEnterprise

Specifies the admin partition of the node to register.

Values

• Default: None
• Data type: String

spec.service

Specifies the service to register. The Service.Service field is required. If Service.ID is not provided, the default is the Service.Service.

You can only specify one service with a given ID per node. We recommend using valid DNS labels for service definition names. Refer to Internet Engineering Task Force's RFC 1123 for additional information. Service names that conform to standard usage ensures compatibility with external DNSs. Refer to Services Configuration Reference for more information.

Values

• Default: None
• Data type: Map

spec.service.address

Specifies a service-specific IP address or hostname. If no value is specified, the IP address of the agent node is used by default. There is no service-side validation of this parameter.

Values

• Default: None
• Data type: String

spec.service.enableTagOverride

Setermines if the anti-entropy feature for the service is enabled.

Set to true to allow external Consul agents to modify tags on the services in the Consul catalog. The local Consul agent ignores updated tags during subsequent sync operations.

This parameter only applies to the locally-registered service. When multiple nodes register a service with the same name, the enable_tag_override configuration and all other service configuration items operate independently.

Refer to Modify anti-entropy synchronization for additional information.

Values

• Default: false
• Data type: Boolean

spec.service.id

Specifies an ID for the service. Services on the same node must have unique IDs. We recommend specifying unique values if the default name conflicts with other services.

Values

• Default: None
• Data type: String

spec.service.locality

Specifies the region and zone in the cloud service provider (CSP) where the service is available. Configure this field to enable Consul to route traffic to the nearest physical service instance. Services inherit the locality configuration of the Consul agent they are registered with, but you can explicitly define locality for your service instances if an override is needed. Refer to Route traffic to local upstreams for additional information.

Values

• Default: None
• Data type: Map that can contain the following parameters:

spec.service.meta

Specifies custom key-value pairs that associate semantic metadata with the service. You can specify up to 64 pairs that meet the following requirements:

• Keys and values must be strings.
• Keys can only contain ASCII characters (A - Z, a- z, 0 - 9, _, and -).
• Keys can not have special characters.
• Keys are limited to 128 characters.
• Values are limited to 512 characters.

Values

• Default: None
• Data type: Map of strings

spec.service.name

Specifies a name for the service. We recommend using valid DNS labels for service definition names for compatibility with external DNSs. The value of this parameter is also used as the service ID if the spec.service.id parameter is not specified.

Values

• Default: None
• Data type: String

spec.service.namespace EnterpriseEnterprise

Specifies the Consul namespace to register the service in. Refer to namespaces for more information.

Values

• Default: None
• Data type: String

spec.service.partition EnterpriseEnterprise

Specifies the Consul admin partition to register the service in. Refer to admin partitions for more information.

Values

• Default: None
• Data type: String

spec.service.port

Specifies a port number for the service. To improve service discoverability, we recommend specifying the port number, as well as an address in the tagged_addresses parameter.

Values

• Default: None
• Data type: Integer

spec.service.socketPath

Specifies the path to the service socket. Specify this parameter to expose the service to the mesh if the service listens on a Unix Domain socket.

Values

• Default: None
• Data type: String

spec.service.taggedAddresses

Configures additional addresses for a node or service. Remote agents and services can communicate with the service using a tagged address as an alternative to the address specified in spec.service.address. You can configure multiple addresses for a node or service. The following tags are supported:

• lan: IPv4 LAN address where the node or service is accessible.
• lan_ipv4: IPv4 LAN address where the node or service is accessible.
• lan_ipv6: IPv6 LAN address where the node or service is accessible.
• virtual: A fixed address for the instances of a given logical service.
• wan: IPv4 WAN address where the node or service is accessible when dialed from a remote data center.
• wan_ipv4: IPv4 WAN address where the node or service is accessible when dialed from a remote data center.
• wan_ipv6: IPv6 WAN address at which the node or service is accessible when being dialed from a remote data center.

Values

• Default: None
• Data type: Map that contains a supported tag and a child map containing the following fields:

spec.service.tags

Specifies a list of string values that add service-level labels. Tag values are opaque to Consul. We recommend using valid DNS labels for service definition IDs for compatibility with external DNSs. In the following example, the service is tagged as v2 and primary:

spec:
  service:
    tags: ["v2", "primary"]

Consul uses tags as an anti-entropy mechanism to maintain the state of the cluster. You can disable the anti-entropy feature for a service using spec.service.enable_tag_override, which enables external agents to modify tags on services in the catalog. Refer to Modify anti-entropy synchronization for additional usage information.

Values

• Default: None
• Data type: Map of strings

spec.service.weights

Configures how a service instance is weighted in a DNS SRV request based on the service's health status. Configuring tells DNS clients to direct more traffic to instances with a higher weight. A use case would be adjusting the weight higher for an instance with large capacity. It could also be used to reduce the load on services with checks in warning status by favoring passing instances with a higher weight.

Larger integer values increase the weight state.

You can specify one or more of the following states and configure an integer value indicating its weight:

• passing
• warning

Services in a critical state are excluded from DNS responses. Services with warning checks are included in responses by default.

Values

• Default: None
• Data type: Map containing the following parameters:

spec.skipNodeUpdate

Specifies whether to skip updating the node's information in the registration. This field is useful in casew where only a health check or service entry on a node needs to be updated or when a register request is intended to update a service entry or health check. In both use cases, node information is not be overwritten, if the node is already registered. Note, if the parameter is enabled for a node that does not exist, it is still be created.

Values

• Default: false
• Data type: Boolean

spec.taggedAddresses

Specifies tagged addresses for the node. Remote agents and services can communicate with the service using a tagged address as an alternative to the address specified in spec.address. You can configure multiple addresses for a node or service. The following tags are supported:

• lan: IPv4 LAN address where the node or service is accessible.
• lan_ipv4: IPv4 LAN address where the node or service is accessible.
• lan_ipv6: IPv6 LAN address where the node or service is accessible.
• virtual: A fixed address for the instances of a given logical service.
• wan: IPv4 WAN address where the node or service is accessible when dialed from a remote data center.
• wan_ipv4: IPv4 WAN address where the node or service is accessible when dialed from a remote data center.
• wan_ipv6: IPv6 WAN address at which the node or service is accessible when being dialed from a remote data center.

Values

• Default: None
• Data type: Map of strings

Examples

The following example demonstrates a common Registration CRD configuration pattern. In this example, Consul registers a database service available at the IP address 10.96.32.66 that runs outside of the Kubernetes cluster where Consul is deployed. Consul runs an HTTP health check on this service every 10 seconds.

apiVersion: consul.hashicorp.com/v1alpha1
kind: Registration
metadata:
  name: external-database
spec:
  node: node-virtual
  check:
    node: node-virtual
    checkId: db-check
    name: db
    serviceName: db
    serviceId: db-external
    notes: "Runs the external health check for the database."
    status: "passing"
    definition:
      http: "10.96.32.66:8081/health"
      intervalDuration: "10s"
      timeoutDuration: "10s"
      deregisterCriticalServiceAfterDuration: "30s"
  service:
    name: db
    id: db-external
    address: "10.96.32.66"
    port: 8081
    weights:
      passing: 1
      warning: 1
  address: 10.96.32.66