luxolus
/
open-consul
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity

Backport of docs - add service sync annotations and k8s service weight annotation into release/1.16.x (#18036) 

* backport of commit e1bf4284947af9edd36e9d6f4d2c32e2d1fe9b14

* backport of commit ddf214e638327cdf4b76d325d3c4194d6e26cee3

* backport of commit e41bd9c4e372c2b83d673d6f5c4afcfb44bdf14f

* backport of commit b9cfc86e145d0b90474a1e13f5f02ce7599d9f0f

* backport of commit 0ddf013d6c4e7d44c0c6dfff8fe0c56e5c4b6ca5

* backport of commit 1b0b513b05c1b14c9eb69f0e74f72fc7a0bba118

* backport of commit 29442ad641b0de0df9753cdd207b9f15bc76e6e5

* backport of commit 5e7ddf5c7ef764e7df8fa4f6cd03431e89e8b441

* backport of commit f2b6fa7b4362ecde79b3b8a9752da6d2774d44d8

* backport of commit 83b84a985a131c0ce2b10351f6dd5ca68cef5bf2

* backport of commit 56d81738cc8143ddec27cc5134af23da4bfc2dd8

* backport of commit 0ab44f06c7249adc8a0ba43c369c66ae1f18e8c8

* backport of commit 69c99fbccb711d32194eefd04419b854cacf8750

* backport of commit b79e1245c1bf765c97462f322c09965314317b0a

* backport of commit fb1441976be9c78a2d658b094e178a0c0f75eb5e

* backport of commit 3b7b2a04242e17fc88296fc248ba491e697697c4

---------

Co-authored-by: David Yu <dyu@hashicorp.com>
This commit is contained in:
hc-github-team-consul-core 2023-07-06 15:00:56 -05:00 committed by GitHub
parent bc18afc199
commit b8f2de3aa0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 57 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

63
website/content/docs/k8s/annotations-and-labels.mdx
View File

@ -9,16 +9,21 @@ description: >-
## Overview ## 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). This allows the user to configure natively configure Consul on select Kubernetes resources (i.e. pods, services).
- [Annotations](#annotations) - [Consul Service Mesh](#consul-service-mesh)
- [Labels](#labels) - [Annotations](#annotations)
- [Labels](#labels)
- [Service Sync](#service-sync)
- [Annotations](#annotations-1)
The noun _connect_ is used throughout this documentation to refer to the connect The noun _connect_ is used throughout this documentation to refer to the connect
subsystem that provides Consul's service mesh capabilities. subsystem that provides Consul's service mesh capabilities.
## Annotations ## Consul Service Mesh
### Annotations
The following Kubernetes resource annotations could be used on a pod to control connect-inject behavior: The following Kubernetes resource annotations could be used on a pod to control connect-inject behavior:
@ -76,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, 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. 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. 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.
@ -133,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]" "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) . the upstream namespace after the service name. For additional details about configuring the injector, refer to [Consul Enterprise namespaces](#consul-enterprise-namespaces) .
```yaml ```yaml
@ -144,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. 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. 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 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 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. peering connection](/consul/docs/k8s/connect/cluster-peering/usage/establish-peering) and set the upstream with a labeled annotation format.
@ -265,7 +270,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\"}]" "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. Resource labels could be used on a Kubernetes service to control connect-inject behavior.
@ -276,3 +281,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 registration to ignore all services except for the one which should be used for routing requests
using Consul. 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
```

8
website/content/docs/k8s/service-sync.mdx
View File

@ -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 as first-class Kubernetes services. This functionality is provided by the
[consul-k8s project](https://github.com/hashicorp/consul-k8s) and can be [consul-k8s project](https://github.com/hashicorp/consul-k8s) and can be
automatically installed and configured using the automatically installed and configured using the
[Consul Helm chart](/consul/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) ![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](/consul/docs/k8s/service-sync#sync-enable-disable). ~> 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](/consul/docs/k8s/service-sync#sync-enable-disable).
The service sync uses an external long-running process in the 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).
[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](/consul/docs/k8s/helm).
The Consul server cluster can run either in or out of a Kubernetes cluster. 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 The Consul server cluster does not need to be running on the same machine