197 lines
9.8 KiB
Plaintext
197 lines
9.8 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Annotations and Labels
|
|
description: >-
|
|
The list of available labels and annotations for running Consul on Kubernetes.
|
|
---
|
|
|
|
# Annotations and Labels
|
|
|
|
## Overview
|
|
|
|
Consul on Kubernetes provides a few options for customizing how connect-inject 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)
|
|
|
|
## Annotations
|
|
|
|
Resource annotations could be used on the Kubernetes pod to control connect-inject behavior.
|
|
|
|
- `consul.hashicorp.com/connect-inject` - If this is "true" then injection
|
|
is enabled. If this is "false" then injection is explicitly disabled.
|
|
The default injector behavior requires pods to opt-in to injection by
|
|
specifying this value as "true". This default can be changed in the
|
|
injector's configuration if desired.
|
|
|
|
- `consul.hashicorp.com/transparent-proxy` - If this is "true", this Pod
|
|
will run with transparent proxy enabled. This means you can use Kubernetes
|
|
DNS to access upstream services and all inbound and outbound traffic within
|
|
the pod is redirected to go through the proxy.
|
|
|
|
- `consul.hashicorp.com/transparent-proxy-overwrite-probes` - If this is "true"
|
|
and transparent proxy is enabled, the Connect injector will overwrite Kubernetes
|
|
HTTP probes to point to the Envoy proxy.
|
|
|
|
- `consul.hashicorp.com/transparent-proxy-exclude-inbound-ports` - A comma-separated
|
|
list of inbound ports to exclude from traffic redirection when running in transparent proxy
|
|
mode.
|
|
|
|
- `consul.hashicorp.com/transparent-proxy-exclude-outbound-cidrs` - A comma-separated
|
|
list of outbound CIDRs to exclude from traffic redirection when running in transparent proxy
|
|
mode.
|
|
|
|
- `consul.hashicorp.com/transparent-proxy-exclude-outbound-ports` - A comma-separated
|
|
list of outbound ports to exclude from traffic redirection when running in transparent proxy
|
|
mode.
|
|
|
|
- `consul.hashicorp.com/transparent-proxy-exclude-uids` - A comma-separated
|
|
list of additional user IDs to exclude from traffic redirection when running in transparent proxy
|
|
mode.
|
|
|
|
- `consul.hashicorp.com/connect-service` - For pods that accept inbound
|
|
connections, this specifies the name of the service that is being
|
|
served. This defaults to the name of the Kubernetes service associated with the pod.
|
|
|
|
If using ACLs, this must be the same name as the Pod's `ServiceAccount`.
|
|
|
|
- `consul.hashicorp.com/connect-service-port` - For pods that accept inbound
|
|
connections, this specifies the port to route inbound connections to. This
|
|
is the port that the service is listening on. The service port defaults to
|
|
the first exposed port on any container in the pod. If specified, the value
|
|
can be the _name_ of a configured port, such as "http" or it can be a direct
|
|
port value such as "8080". This is the port of the _service_, the proxy
|
|
public listener will listen on a dynamic port.
|
|
|
|
- `consul.hashicorp.com/connect-service-upstreams` - The list of upstream
|
|
services that this pod needs to connect to via Connect along with a static
|
|
local port to listen for those connections. When transparent proxy is enabled,
|
|
this annotation is optional.
|
|
|
|
- Services
|
|
|
|
The name of the service is the name of the service registered with Consul. You can optionally specify datacenters with this annotation.
|
|
|
|
```yaml
|
|
annotations:
|
|
"consul.hashicorp.com/connect-service-upstreams":"[service-name]:[port]:[optional datacenter]"
|
|
```
|
|
|
|
- Consul Enterprise Namespaces
|
|
|
|
If running Consul Enterprise 1.7+, your upstream services may be running in different
|
|
namespaces. The upstream namespace can be specified after the service name
|
|
as `[service-name].[namespace]`. See [Consul Enterprise Namespaces](#consul-enterprise-namespaces)
|
|
below for more details on configuring the injector.
|
|
|
|
```yaml
|
|
annotations:
|
|
"consul.hashicorp.com/connect-service-upstreams":"[service-name].[service-namespace]:[port]:[optional datacenter]"
|
|
```
|
|
|
|
-> **NOTE:** If the namespace is not specified it will default to the namespace
|
|
of the source service.
|
|
|
|
~> **WARNING:** Setting a namespace when not using Consul Enterprise or using a version < 1.7
|
|
is not supported. It will be treated as part of the service name.
|
|
|
|
- [Prepared Query](/docs/connect/proxies#dynamic-upstreams-require-native-integration)
|
|
|
|
```yaml
|
|
annotations:
|
|
'consul.hashicorp.com/connect-service-upstreams': 'prepared_query:[query name]:[port]'
|
|
```
|
|
|
|
- Multiple Upstreams
|
|
|
|
If you would like to specify multiple services or upstreams, delimit them with commas
|
|
|
|
```yaml
|
|
annotations:
|
|
"consul.hashicorp.com/connect-service-upstreams":"[service-name]:[port]:[optional datacenter],[service-name]:[port]:[optional datacenter]"
|
|
```
|
|
|
|
```yaml
|
|
annotations:
|
|
"consul.hashicorp.com/connect-service-upstreams":"[service-name]:[port]:[optional datacenter],prepared_query:[query name]:[port]"
|
|
```
|
|
|
|
- `consul.hashicorp.com/envoy-extra-args` - A space-separated list of [arguments](https://www.envoyproxy.io/docs/envoy/latest/operations/cli)
|
|
to be passed to the injected envoy binary.
|
|
|
|
```yaml
|
|
annotations:
|
|
consul.hashicorp.com/envoy-extra-args: '--log-level debug --disable-hot-restart'
|
|
```
|
|
|
|
- `consul.hashicorp.com/kubernetes-service` - Specifies the name of the Kubernetes service used for Consul service registration.
|
|
This is useful when multiple Kubernetes services reference the same deployment. Any service that does not match the name
|
|
specified in this annotation is ignored. When not specified no service is ignored.
|
|
|
|
```yaml
|
|
annotations:
|
|
consul.hashicorp.com/kubernetes-service: 'service-name-to-use'
|
|
```
|
|
|
|
- `consul.hashicorp.com/service-tags` - A comma separated list of tags that will
|
|
be applied to the Consul service and its sidecar.
|
|
|
|
```yaml
|
|
annotations:
|
|
consul.hashicorp.com/service-tags: foo,bar,baz
|
|
```
|
|
|
|
If you need your tag to have a comma in it you can escape the comma with `\,`. For example,
|
|
`consul.hashicorp.com/service-tags: foo\,bar\,baz` will become the single tag `foo,bar,baz`.
|
|
|
|
- `consul.hashicorp.com/service-meta-<YOUR_KEY>` - Set Consul meta key/value
|
|
pairs that will be applied to the Consul service and its sidecar.
|
|
The key will be what comes after `consul.hashicorp.com/service-meta-`, e.g.
|
|
`consul.hashicorp.com/service-meta-foo: bar` will result in `foo: bar`.
|
|
|
|
```yaml
|
|
annotations:
|
|
consul.hashicorp.com/service-meta-foo: baz
|
|
consul.hashicorp.com/service-meta-bar: baz
|
|
```
|
|
|
|
- `consul.hashicorp.com/sidecar-proxy-` - Override default resource settings for
|
|
the sidecar proxy container.
|
|
The defaults are set in Helm config via the [`connectInject.sidecarProxy.resources`](/docs/k8s/helm#v-connectinject-sidecarproxy-resources) key.
|
|
|
|
- `consul.hashicorp.com/sidecar-proxy-cpu-limit` - Override the default CPU limit.
|
|
- `consul.hashicorp.com/sidecar-proxy-cpu-request` - Override the default CPU request.
|
|
- `consul.hashicorp.com/sidecar-proxy-memory-limit` - Override the default memory limit.
|
|
- `consul.hashicorp.com/sidecar-proxy-memory-request` - Override the default memory request.
|
|
|
|
- `consul.hashicorp.com/consul-sidecar-` - Override default resource settings for
|
|
the `consul-sidecar` container.
|
|
The defaults are set in Helm config via the [`global.consulSidecarContainer.resources`](/docs/k8s/helm#v-global-consulsidecarcontainer) key.
|
|
|
|
- `consul.hashicorp.com/consul-sidecar-cpu-limit` - Override the default CPU limit.
|
|
- `consul.hashicorp.com/consul-sidecar-cpu-request` - Override the default CPU request.
|
|
- `consul.hashicorp.com/consul-sidecar-memory-limit` - Override the default memory limit.
|
|
- `consul.hashicorp.com/consul-sidecar-memory-request` - Override the default memory request.
|
|
|
|
- `consul.hashicorp.com/enable-metrics` - Override the default Helm value [`connectInject.metrics.defaultEnabled`](/docs/k8s/helm#v-connectinject-metrics-defaultenabled).
|
|
- `consul.hashicorp.com/enable-metrics-merging` - Override the default Helm value [`connectInject.metrics.defaultEnableMerging`](/docs/k8s/helm#v-connectinject-metrics-defaultenablemerging).
|
|
- `consul.hashicorp.com/merged-metrics-port` - Override the default Helm value [`connectInject.metrics.defaultMergedMetricsPort`](/docs/k8s/helm#v-connectinject-metrics-defaultmergedmetricsport).
|
|
- `consul.hashicorp.com/prometheus-scrape-port` - Override the default Helm value [`connectInject.metrics.defaultPrometheusScrapePort`](/docs/k8s/helm#v-connectinject-metrics-defaultprometheusscrapeport).
|
|
- `consul.hashicorp.com/prometheus-scrape-path` - Override the default Helm value [`connectInject.metrics.defaultPrometheusScrapePath`](/docs/k8s/helm#v-connectinject-metrics-defaultprometheusscrapepath).
|
|
- `consul.hashicorp.com/service-metrics-port` - Set the port where the Connect service exposes metrics.
|
|
- `consul.hashicorp.com/service-metrics-path` - Set the path where the Connect service exposes metrics.
|
|
- `consul.hashicorp.com/connect-inject-mount-volume` - Comma separated list of container names to mount the connect-inject volume into. The volume will be mounted at `/consul/connect-inject`. The connect-inject volume contains Consul internals data needed by the other sidecar containers, for example the `consul` binary, and the Pod's Consul ACL token. This data can be valuable for advanced use-cases, such as making requests to the Consul API from within application containers.
|
|
|
|
## Labels
|
|
|
|
Resource labels could be used on a Kubernetes service to control connect-inject behavior.
|
|
|
|
- `consul.hashicorp.com/service-ignore` - This label can be set on a Kubernetes Service.
|
|
If set to "true", the service will not be used to register a Consul endpoint. This can be
|
|
useful in cases where 2 or more services point to the same deployment. Consul cannot register
|
|
multiple endpoints to the same deployment. This label can be used to tell the endpoint
|
|
registration to ignore all services except for the one which should be used for routing requests
|
|
using Consul.
|
|
|