From 0c4b6d7dbf7324954eef7855e695593f08a5523b Mon Sep 17 00:00:00 2001 From: hc-github-team-consul-core Date: Thu, 6 Jul 2023 15:45:26 -0500 Subject: [PATCH] Backport of docs - add service sync annotations and k8s service weight annotation into release/1.14.x (#18038) * backport of commit e1bf4284947af9edd36e9d6f4d2c32e2d1fe9b14 * manual merge --------- Co-authored-by: David Yu --- .../docs/k8s/annotations-and-labels.mdx | 73 +++++++++++++++++-- website/content/docs/k8s/service-sync.mdx | 8 +- 2 files changed, 67 insertions(+), 14 deletions(-) diff --git a/website/content/docs/k8s/annotations-and-labels.mdx b/website/content/docs/k8s/annotations-and-labels.mdx index b22db2de8f79..cd0afce61273 100644 --- a/website/content/docs/k8s/annotations-and-labels.mdx +++ b/website/content/docs/k8s/annotations-and-labels.mdx @@ -9,13 +9,21 @@ description: >- ## Overview -Consul on Kubernetes provides a few options for customizing how connect-inject behavior should be configured. +Consul on Kubernetes provides a few options for customizing how connect-inject or service sync behavior should be configured. This allows the user to configure natively configure Consul on select Kubernetes resources (i.e. pods, services). -- [Annotations](#annotations) -- [Labels](#labels) +- [Consul Service Mesh](#consul-service-mesh) + - [Annotations](#annotations) + - [Labels](#labels) +- [Service Sync](#service-sync) + - [Annotations](#annotations-1) -## Annotations +The noun _connect_ is used throughout this documentation to refer to the connect +subsystem that provides Consul's service mesh capabilities. + +## Consul Service Mesh + +### Annotations The following Kubernetes resource annotations could be used on a pod to control connect-inject behavior: @@ -73,7 +81,7 @@ The following Kubernetes resource annotations could be used on a pod to control local port to listen for those connections. When transparent proxy is enabled, this annotation is optional. This annotation can be either _labeled_ or _unlabeled_. We recommend the labeled format because it has a more consistent syntax and can be used to reference cluster peers as upstreams. -- **Labeled** (requires Consul on Kubernetes v0.45.0+): + - **Labeled**: The labeled annotation format allows you to reference any service as an upstream. You can specify a Consul Enterprise namespace. You can also specify an admin partition in the same datacenter, a cluster peer, or a WAN-federated datacenter. @@ -130,7 +138,7 @@ The following Kubernetes resource annotations could be used on a pod to control "consul.hashicorp.com/connect-service-upstreams":"[service-name]:[port]:[optional datacenter]" ``` - - Namespace (requires Consul Enterprise 1.7+): Upstream services may be running in a different namespace. Place + - Namespace: Upstream services may be running in a different namespace. Place the upstream namespace after the service name. For additional details about configuring the injector, refer to [Consul Enterprise namespaces](#consul-enterprise-namespaces) . ```yaml @@ -141,7 +149,7 @@ The following Kubernetes resource annotations could be used on a pod to control If the namespace is not specified, the annotation defaults to the namespace of the source service. Consul Enterprise v1.7 and older interprets the value placed in the namespace position as part of the service name. - - Admin partitions (requires Consul Enterprise 1.11+): Upstream services may be running in a different + - Admin partitions: Upstream services may be running in a different partition. When specifying a partition, you must also specify a namespace. Place the partition name after the namespace. If you specify the name of the datacenter, it must be the local datacenter. Communicating across partitions using this method is only supported within a datacenter. For cross partition communication across datacenters, [establish a cluster peering connection](/consul/docs/k8s/connect/cluster-peering/usage/establish-peering) and set the upstream with a labeled annotation format. @@ -188,6 +196,13 @@ The following Kubernetes resource annotations could be used on a pod to control consul.hashicorp.com/kubernetes-service: 'service-name-to-use' ``` +- `consul.hashicorp.com/service-weight:` - Configure ability to support weighted loadbalancing by service annotation for Catalog Sync. The integer provided will be applied as a weight for the `passing` state for the health of the service. See [weights](/consul/docs/services/configuration/services-configuration-reference#weights) in service configuration for more information on how this is leveraged for services in the Catalog. + + ```yaml + annotations: + consul.hashicorp.com/service-weight: 10 + ``` + - `consul.hashicorp.com/service-tags` - A comma separated list of tags that will be applied to the Consul service and its sidecar. @@ -262,7 +277,7 @@ The following Kubernetes resource annotations could be used on a pod to control "consul.hashicorp.com/consul-sidecar-user-volume-mount": "[{\"name\": \"secrets-store-mount\", \"mountPath\": \"/mnt/secrets-store\"}]" ``` -## Labels +### Labels Resource labels could be used on a Kubernetes service to control connect-inject behavior. @@ -273,3 +288,45 @@ Resource labels could be used on a Kubernetes service to control connect-inject registration to ignore all services except for the one which should be used for routing requests using Consul. +## Service Sync + +### Annotations + +The following Kubernetes resource annotations could be used on a pod to [Service Sync](https://developer.hashicorp.com/consul/docs/k8s/service-sync) behavior: + +- `consul.hashicorp.com/service-sync`: If this is set to `true`, then the Kubernetes service is explicitly configured to be synced to Consul. + + ```yaml + annotations: + 'consul.hashicorp.com/service-sync': 'true' + ``` + +- `consul.hashicorp.com/service-port`: Configures the port to register to the Consul Catalog for the Kubernetes service. The annotation value may be a name of a port (recommended) or an exact port value. Refer to [service ports](https://developer.hashicorp.com/consul/docs/k8s/service-sync#service-ports) for more information. + + ```yaml + annotations: + 'consul.hashicorp.com/service-port': 'http' + ``` + +- `consul.hashicorp.com/service-tags`: A comma separated list of strings (without whitespace) to use for registering tags to the service registered to Consul. These custom tags automatically include the `k8s` tag which can't be disabled. + + ```yaml + annotations: + 'consul.hashicorp.com/service-tags': 'primary,foo' + ``` + +- `consul.hashicorp.com/service-meta-KEY`: A map for specifying service metadata for Consul services. The "KEY" below can be set to any key. This allows you to set multiple meta values. + + ```yaml + annotations: + 'consul.hashicorp.com/service-meta-KEY': 'value' + ``` + +- `consul.hashicorp.com/service-weight:` - Configures ability to support weighted loadbalancing by service annotation for Catalog Sync. The integer provided will be applied as a weight for the `passing` state for the health of the service. Refer to [weights](/consul/docs/services/configuration/services-configuration-reference#weights) in service configuration for more information on how this is leveraged for services in the Consul catalog. + + ```yaml + annotations: + consul.hashicorp.com/service-weight: 10 + ``` + + diff --git a/website/content/docs/k8s/service-sync.mdx b/website/content/docs/k8s/service-sync.mdx index e73459f2e7d7..56ad75b0b5ee 100644 --- a/website/content/docs/k8s/service-sync.mdx +++ b/website/content/docs/k8s/service-sync.mdx @@ -12,7 +12,7 @@ services are available to Consul agents and services in Consul can be available as first-class Kubernetes services. This functionality is provided by the [consul-k8s project](https://github.com/hashicorp/consul-k8s) and can be automatically installed and configured using the -[Consul Helm chart](/docs/k8s/installation/install). +[Consul K8s Helm chart](/consul/docs/k8s/installation/install). ![screenshot of a Kubernetes service in the UI](/img/k8s-service.png) @@ -31,11 +31,7 @@ service discovery, including hosted services like databases. ~> Enabling both Service Mesh and Service Sync on the same Kubernetes services is not supported, as Service Mesh also registers Kubernetes service instances to Consul. Ensure that Service Sync is only enabled for namespaces and services that are not injected with the Consul sidecar for Service Mesh as described in [Sync Enable/Disable](/docs/k8s/service-sync#sync-enable-disable). -The service sync uses an external long-running process in the -[consul-k8s project](https://github.com/hashicorp/consul-k8s). This process -can run either inside or outside of a Kubernetes cluster. However, running this process within -the Kubernetes cluster is generally easier since it is automated using the -[Helm chart](/docs/k8s/helm). +The service sync feature deploys a long-running process which can run either inside or outside of a Kubernetes cluster. However, running this process within the Kubernetes cluster is generally easier since it is automated using the [Helm chart](/consul/docs/k8s/helm). The Consul server cluster can run either in or out of a Kubernetes cluster. The Consul server cluster does not need to be running on the same machine