Skip to content

Commit

Permalink
docs - add service sync annotations and k8s service weight annotation (
Browse files Browse the repository at this point in the history
…#18032)

* Docs for hashicorp/consul-k8s#2293
* remove versions for enterprise features since they are old

---------

Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com>
  • Loading branch information
David Yu and im2nguyen authored Jul 6, 2023
1 parent 820cdbb commit 85f2ae0
Show file tree
Hide file tree
Showing 2 changed files with 57 additions and 14 deletions.
63 changes: 55 additions & 8 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 @@ -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]"
```

- 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
Expand All @@ -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.
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.
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,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
```


8 changes: 2 additions & 6 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,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).

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](/consul/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
Expand Down

0 comments on commit 85f2ae0

Please sign in to comment.