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
|
||||
```
|
||||
|
||||
### 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
|
||||
|
||||
The Connect sidecar proxy is injected via a
|
||||
|
|
|
|||
|
|
@ -553,6 +553,10 @@
|
|||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "Annotations and Labels",
|
||||
"path": "k8s/annotations-and-labels"
|
||||
},
|
||||
{
|
||||
"title": "Consul DNS",
|
||||
"path": "k8s/dns"
|
||||
|
|
|
|||
Loading…
Reference in New Issue