Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs - add service sync annotations and k8s service weight annotation #18032

Merged
merged 16 commits into from
Jul 6, 2023
53 changes: 47 additions & 6 deletions website/content/docs/k8s/annotations-and-labels.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -9,16 +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)

The noun _connect_ is used throughout this documentation to refer to the connect
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:

Expand Down Expand Up @@ -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,
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.

Expand Down Expand Up @@ -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\"}]"
```

## Labels
### Labels

Resource labels could be used on a Kubernetes service to control connect-inject behavior.

Expand All @@ -276,3 +281,39 @@ 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. See [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 setting multiple meta values.

```yaml
annotations:
'consul.hashicorp.com/service-meta-KEY': 'value'
```
- `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 Consul catalog.

```yaml
annotations:
consul.hashicorp.com/service-weight: 10
```


5 changes: 2 additions & 3 deletions website/content/docs/k8s/service-sync.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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](/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)

Expand All @@ -31,8 +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).

The service sync uses an external long-running process in the
[consul-k8s project](https://github.com/hashicorp/consul-k8s). This process
The service sync feature deploys a long-running process which can
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).
Expand Down