github
/
consul
mirror of https://github.com/hashicorp/consul
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
consul/website/content/docs/connect/config-entries/registration.mdx

670 lines
28 KiB
Plaintext
Raw Normal View History

docs: External Services CRD (#21264) * Initial reference page structure * Most specifications * Reference page details complete * Enterprise alerts * Overview page * Overview page * TGW note * fixes * Apply suggestions from code review Co-authored-by: Blake Covarrubias <blake@covarrubi.as> * Update website/content/docs/k8s/deployment-configurations/external-service.mdx Co-authored-by: Blake Covarrubias <blake@covarrubi.as> * Update website/content/docs/connect/config-entries/registration.mdx * Update website/content/docs/connect/config-entries/registration.mdx --------- Co-authored-by: Blake Covarrubias <blake@covarrubi.as>
2024-06-11 19:58:12 +00:00
---
layout: docs
page_title: Registration CRD configuration reference
description: The Registration CRD enables Consul on Kubernetes to register an external service without a terminating gateway. Learn how to configure a Registration CRD in YAML with a specification reference, configuration model, a complete example, and example code.
---
# 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](/consul/docs/k8s/deployment-configurations/external-service) 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`](#apiversion): string | required | must be set to `consul.hashicorp.com/v1alpha1`
- [`kind`](#kind): string | required | must be set to `Registration`
- [`metadata`](#metadata): map
- [`name`](#metadata-name): string
- [`spec`](#spec): map | required
- [`address`](#spec-address): string
- [`check`](#spec-check): map
- [`checkId`](#spec-check-checkid): string
- [`definition`](#spec-check-definition): map
- [`body`](#spec-check-definition): string
- [`deregisterCriticalServiceAfterDuration`](#spec-check-definition): string
- [`grpc`](#spec-check-definition): string
- [`grpcUseTLS`](#spec-check-definition): boolean | `false`
- [`header`](#spec-check-definition): map of strings
- [`http`](#spec-check-definition): string
- [`intervalDuration`](#spec-check-definition): string
- [`method`](#spec-check-definition): string
- [`osService`](#spec-check-definition): string
- [`tcp`](#spec-check-definition): string
- [`tcpUseTLS`](#spec-check-definition): boolean
- [`timeoutDuration`](#spec-check-definition): string
- [`tlsServerName`](#spec-check-definition): string
- [`tlsSkipVerify`](#spec-check-definition): boolean | `false`
- [`udp`](#spec-check-definition): string
- [`exposedPort`](#spec-check-exposed-port): integer
- [`name`](#spec-check-name): string
- [`namespace`](#spec-check-namespace): string <EnterpriseAlert inline />
- [`node`](#spec-check-node): string
- [`notes`](#spec-check-notes): string
- [`output`](#spec-check-output): string
- [`partition`](#spec-check-partition): string <EnterpriseAlert inline />
- [`serviceId`](#spec-check-serviceid): string
- [`serviceName`](#spec-check-servicename): string
- [`status`](#spec-check-status): string
- [`type`](#spec-check-type): string
- [`datacenter`](#spec-datacenter): string
- [`id`](#spec-id): string
- [`locality`](#spec-locality): map
- [`region`](#spec-locality): string
- [`zone`](#spec-locality): string
- [`node`](#spec-node): string
- [`nodeMeta`](#spec-nodemeta): map of strings
- [`partition`](#spec-partition): string <EnterpriseAlert inline />
- [`service`](#spec-service): map
- [`address`](#spec-service-address): string
- [`enableTagOverride`](#spec-service-enabletagoverride): boolean | `false`
- [`id`](#spec-service-id): string
- [`locality`](#spec-service-locality): map
- [`region`](#spec-service-locality): string
- [`zone`](#spec-service-locality): string
- [`meta`](#spec-service-meta): map of strings
- [`name`](#spec-service-name): string
- [`namespace`](#spec-service-namespace): string <EnterpriseAlert inline />
- [`partition`](#spec-service-partition): string <EnterpriseAlert inline />
- [`port`](#spec-service-port): integer
- [`socketPath`](#spec-service-socketpath): string
- [`taggedAddresses`](#spec-service-taggedaddresses): map
- [`address`](#spec-service-taggedaddresses): string
- [`port`](#spec-service-port): integer
- [`tags`](#spec-service-tags): map of strings
- [`weights`](#spec-service-weights): map
- [`passing`](#spec-service-weights): integer | `1`
- [`warning`](#spec-service-weights): integer | `1`
- [`skipNodeUpdate`](#spec-skipnodeupdate): boolean | `false`
- [`taggedAddresses`](#spec-taggedaddresses): map of strings
## Complete configuration
When every field is defined, a `Registration` CRD has the following form:
```yaml
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](/consul/docs/services/configuration/checks-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:
| Parameter | Description | Type | Default |
| :------------------------------------------------------------- | :---------- | :---------- | :---------- |
| `spec.check.definition.body` | Specifies JSON attributes to send in HTTP check requests. You must escape the quotation marks around the keys and values for each attribute. | String | None |
| `spec.check.definition.deregisterCriticalServiceAfterDuration` | Specifies how long a service and its associated checks are allowed to be in a `critical` state. Consul deregisters services if they are `critical` for the specified amount of time. This parameter is required to configure `spec.check.definition`. | String | `"30s"` |
| `spec.check.definition.grpc` | Specifies the gRPC endpoint, including port number, to send requests to. Append the endpoint with `:/` and a service identifier to check a specific service. The endpoint must support the [gRPC health checking protocol](https://github.com/grpc/grpc/blob/master/doc/health-checking.md). | String | None |
| `spec.check.definition.grpcUseTLS` | Enables TLS for gRPC checks when set to `true`. | Boolean | `false` |
| `spec.check.definition.header` | Specifies header fields to send in HTTP check requests. | Map of strings | None |
| `spec.check.definition.http` | Specifies an HTTP endpoint to send requests to. | String | None |
| `spec.check.definition.intervalDuration` | Specifies how frequently to run the health check. This parameter is required to configure `spec.check.definition`. | String | `"5s"` |
| `spec.check.definition.method` | Specifies the request method to send during HTTP checks. | String | `GET` |
| `spec.check.definition.osService` | Specifies the name of the name of a service to check during an OSService check. | String | None |
| `spec.check.definition.tcp` | Specifies an IP address or host and port number that the check establishes a TCP connection with. | String | None |
| `spec.check.definition.tcpUseTLS` | Enables TLS for TCP checks when set to `true`. | Boolean | `false` |
| `spec.check.definition.timeoutDuration` | Specifies how long unsuccessful requests take to end with a timeout. This parameter is required to configure `spec.check.definition`. | String | `"10s"` |
| `spec.check.definition.tlsServerName` | Specifies the server name used to verify the hostname on the returned certificates unless `tls_skip_verify` is configured. This value is also included in the client's handshake to support SNI. It is recommended that this field be left unspecified. Refer to [health check configuration reference](/consul/docs/services/configuration/checks-configuration-reference#check-block) for more information. | String | None |
| `spec.check.definition.tlsSkipVerify` | Determines if the check verifies the chain and hostname of the certificate that the server presents. Set to `true` to disable verification. We recommend setting to `false` in production environments. | Boolean | `false` |
| `spec.check.definition.udp` | Specifies an IP address or host and port number for the check to send UDP datagrams to. | String | None |
### `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`](#spec-service-id).
#### Values
- Default: None
- Data type: String
### `spec.check.namespace` <EnterpriseAlert inline />
Specifies the Consul namespace the health check applies to. Refer to [namespaces](/consul/docs/enterprise/namespace) 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` <EnterpriseAlert inline />
Specifies the Consul admin partition the health check applies to. Refer to [admin partitions](/consul/docs/enterprise/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:
| Parameter | Description | Data type | Default |
| :-------- | :---------- | :-------- | :------ |
| `spec.locality.region` | Specifies the region where the node is running. Consul assigns this value to services registered to that agent. When service proxy regions match, Consul is able to prioritize routes between service instances in the same region over instances in other regions. You must specify values that are consistent with how regions are defined in your network, for example `us-west-1` for networks in AWS. | String | None |
| `spec.locality.zone` | Specifies the availability zone where the node is running. Consul assigns this value to services registered to that agent. When service proxy regions match, Consul is able to prioritize routes between service instances in the same region and zone over instances in other regions and zones. When healthy service instances are available in multiple zones within the most-local region, Consul prioritizes instances that also match the downstream proxy's `zone`. You must specify values that are consistent with how zones are defined in your network, for example `us-west-1a` for networks in AWS. | String | None |
### `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` <EnterpriseAlert inline />
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](https://datatracker.ietf.org/doc/html/rfc1123#page-72) for additional information. Service names that conform to standard usage ensures compatibility with external DNSs. Refer to [Services Configuration Reference](/consul/docs/services/configuration/services-configuration-reference#name) 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](/consul/docs/services/usage/define-services#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](/consul/docs/connect/manage-traffic/route-to-local-upstreams) for additional information.
#### Values
- Default: None
- Data type: Map that can contain the following parameters:
| Parameter | Description | Data type | Default |
| :-------- | :---------- | :-------- | :------ |
| `spec.service.locality.region` | Specifies the region where the Consul agent is running. Consul assigns this value to services registered to that agent. When service proxy regions match, Consul is able to prioritize routes between service instances in the same region over instances in other regions. You must specify values that are consistent with how regions are defined in your network, for example `us-west-1` for networks in AWS. | String | None |
| `spec.service.locality.zone` | Specifies the availability zone where the Consul agent is running. Consul assigns this value to services registered to that agent. When service proxy regions match, Consul is able to prioritize routes between service instances in the same region and zone over instances in other regions and zones. When healthy service instances are available in multiple zones within the most-local region, Consul prioritizes instances that also match the downstream proxy's `zone`. You must specify values that are consistent with how zones are defined in your network, for example `us-west-1a` for networks in AWS. | String | None |
### `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` <EnterpriseAlert inline />
Specifies the Consul namespace to register the service in. Refer to [namespaces](/consul/docs/enterprise/namespaces) for more information.
#### Values
- Default: None
- Data type: String
### `spec.service.partition` <EnterpriseAlert inline />
Specifies the Consul admin partition to register the service in. Refer to [admin partitions](/consul/docs/enterprise/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`](#spec-serviceaddress). 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:
| Parameter | Description | Type | Default |
| :------------------------------------- | :---------------------------- | :---------- | :---------- |
| `spec.service.taggedAddresses.address` | The address saved in the tag. | String | None |
| `spec.service.taggedAddresses.port` | The port saved in the tag. | String | None |
### `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`:
```yaml
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`](#spec-service-enabletagoverride), which enables external agents to modify tags on services in the catalog. Refer to [Modify anti-entropy synchronization](/consul/docs/services/usage/define-services#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:
| Parameter | Description | Type | Default |
| :----------------------------- | :---------------------------- | :---------- | :---------- |
| `spec.service.weights.passing` | Higher values increases the likelihood that a request is routed to a service in a `passing` state. | Integer | `1` |
| `spec.service.weights.warning` | Higher values increases the likelihood that a request is routed to a service in a `warning` state. | Integer | `1` |
### `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`](#spec-serviceaddress). 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.
```yaml
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
```