mirror of https://github.com/status-im/consul.git
Separate Annotations/Labels and Add `service-ignore` to Docs (#12323)
* Separate Annotations and Labels and add service-ignore label * changes to structure and call out for pod * add description and TOC * Update annotations-and-labels.mdx Co-authored-by: David Yu <dyu@hashicorp.com>
This commit is contained in:
Thomas Eckert
GitHub
parent
8110ecc93b
commit
6051c68620
|
|
@ -0,0 +1,186 @@
|
||||||
|
---
|
||||||
|
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 connnect-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/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.
|
||||||
|
|
||||||
|
## 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.
|
||||||
|
|
||||||
|
|
@ -220,164 +220,6 @@ $ kubectl exec deploy/static-client -- curl --silent http://static-server/
|
||||||
command terminated with exit code 52
|
command terminated with exit code 52
|
||||||
```
|
```
|
||||||
|
|
||||||
### Available Annotations
|
|
||||||
|
|
||||||
Pod annotations can be used to configure the injection 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/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.
|
|
||||||
|
|
||||||
## Installation and Configuration
|
## Installation and Configuration
|
||||||
|
|
||||||
The Connect sidecar proxy is injected via a
|
The Connect sidecar proxy is injected via a
|
||||||
|
|
|
||||||
|
|
@ -553,6 +553,10 @@
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
},
|
},
|
||||||
|
{
|
||||||
|
"title": "Annotations and Labels",
|
||||||
|
"path": "k8s/annotations-and-labels"
|
||||||
|
},
|
||||||
{
|
{
|
||||||
"title": "Consul DNS",
|
"title": "Consul DNS",
|
||||||
"path": "k8s/dns"
|
"path": "k8s/dns"
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue