mirror of https://github.com/hashicorp/consul
Browse Source
* 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>pull/12367/head
Thomas Eckert
3 years ago
committed by
GitHub
3 changed files with 190 additions and 158 deletions
@ -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. |
||||
|
||||
Loading…
Reference in new issue