From 6051c68620675f34bb9110ef3a6d2f1e6056da9a Mon Sep 17 00:00:00 2001 From: Thomas Eckert Date: Wed, 16 Feb 2022 12:53:13 -0500 Subject: [PATCH] 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 --- .../docs/k8s/annotations-and-labels.mdx | 186 ++++++++++++++++++ website/content/docs/k8s/connect/index.mdx | 158 --------------- website/data/docs-nav-data.json | 4 + 3 files changed, 190 insertions(+), 158 deletions(-) create mode 100644 website/content/docs/k8s/annotations-and-labels.mdx diff --git a/website/content/docs/k8s/annotations-and-labels.mdx b/website/content/docs/k8s/annotations-and-labels.mdx new file mode 100644 index 0000000000..e995aabc58 --- /dev/null +++ b/website/content/docs/k8s/annotations-and-labels.mdx @@ -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-` - 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. + diff --git a/website/content/docs/k8s/connect/index.mdx b/website/content/docs/k8s/connect/index.mdx index 7d33fbb7df..2055dad661 100644 --- a/website/content/docs/k8s/connect/index.mdx +++ b/website/content/docs/k8s/connect/index.mdx @@ -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-` - 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 diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 1acb4ffb06..5138a99878 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -553,6 +553,10 @@ } ] }, + { + "title": "Annotations and Labels", + "path": "k8s/annotations-and-labels" + }, { "title": "Consul DNS", "path": "k8s/dns"