From 61291ef9c5aad9744a912b0d64de5b7e4811446c Mon Sep 17 00:00:00 2001 From: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> Date: Thu, 1 Sep 2022 16:22:11 -0700 Subject: [PATCH] Docs cni plugin (#14009) Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> --- .../docs/connect/transparent-proxy.mdx | 287 ++++++++++-------- .../clients-outside-kubernetes.mdx | 0 .../consul-enterprise.mdx | 0 .../multi-cluster/index.mdx | 0 .../multi-cluster/kubernetes.mdx | 0 .../multi-cluster/vms-and-kubernetes.mdx | 0 .../servers-outside-kubernetes.mdx | 0 .../single-dc-multi-k8s.mdx | 0 .../data-integration/bootstrap-token.mdx | 0 .../vault/data-integration/connect-ca.mdx | 0 .../data-integration/enterprise-license.mdx | 0 .../vault/data-integration/gossip.mdx | 0 .../vault/data-integration/index.mdx | 0 .../data-integration/partition-token.mdx | 0 .../data-integration/replication-token.mdx | 0 .../vault/data-integration/server-tls.mdx | 0 .../snapshot-agent-config.mdx | 0 .../vault/data-integration/webhook-certs.mdx | 0 .../vault/index.mdx | 0 .../vault/systems-integration.mdx | 0 .../vault/wan-federation.mdx | 0 .../docs/k8s/installation/install-cli.mdx | 98 +++++- .../content/docs/k8s/installation/install.mdx | 202 +++++------- .../platforms/self-hosted-kubernetes.mdx | 0 website/data/docs-nav-data.json | 146 ++++----- website/redirects.js | 246 +++++++++++++++ 26 files changed, 652 insertions(+), 327 deletions(-) rename website/content/docs/k8s/{installation => }/deployment-configurations/clients-outside-kubernetes.mdx (100%) rename website/content/docs/k8s/{installation => }/deployment-configurations/consul-enterprise.mdx (100%) rename website/content/docs/k8s/{installation => deployment-configurations}/multi-cluster/index.mdx (100%) rename website/content/docs/k8s/{installation => deployment-configurations}/multi-cluster/kubernetes.mdx (100%) rename website/content/docs/k8s/{installation => deployment-configurations}/multi-cluster/vms-and-kubernetes.mdx (100%) rename website/content/docs/k8s/{installation => }/deployment-configurations/servers-outside-kubernetes.mdx (100%) rename website/content/docs/k8s/{installation => }/deployment-configurations/single-dc-multi-k8s.mdx (100%) rename website/content/docs/k8s/{installation => deployment-configurations}/vault/data-integration/bootstrap-token.mdx (100%) rename website/content/docs/k8s/{installation => deployment-configurations}/vault/data-integration/connect-ca.mdx (100%) rename website/content/docs/k8s/{installation => deployment-configurations}/vault/data-integration/enterprise-license.mdx (100%) rename website/content/docs/k8s/{installation => deployment-configurations}/vault/data-integration/gossip.mdx (100%) rename website/content/docs/k8s/{installation => deployment-configurations}/vault/data-integration/index.mdx (100%) rename website/content/docs/k8s/{installation => deployment-configurations}/vault/data-integration/partition-token.mdx (100%) rename website/content/docs/k8s/{installation => deployment-configurations}/vault/data-integration/replication-token.mdx (100%) rename website/content/docs/k8s/{installation => deployment-configurations}/vault/data-integration/server-tls.mdx (100%) rename website/content/docs/k8s/{installation => deployment-configurations}/vault/data-integration/snapshot-agent-config.mdx (100%) rename website/content/docs/k8s/{installation => deployment-configurations}/vault/data-integration/webhook-certs.mdx (100%) rename website/content/docs/k8s/{installation => deployment-configurations}/vault/index.mdx (100%) rename website/content/docs/k8s/{installation => deployment-configurations}/vault/systems-integration.mdx (100%) rename website/content/docs/k8s/{installation => deployment-configurations}/vault/wan-federation.mdx (100%) rename website/content/docs/k8s/{installation => }/platforms/self-hosted-kubernetes.mdx (100%) diff --git a/website/content/docs/connect/transparent-proxy.mdx b/website/content/docs/connect/transparent-proxy.mdx index 57ad48ba7a..a60bb72d00 100644 --- a/website/content/docs/connect/transparent-proxy.mdx +++ b/website/content/docs/connect/transparent-proxy.mdx @@ -9,72 +9,59 @@ description: |- # Transparent Proxy -Transparent proxy allows applications to communicate through the mesh without changing their configuration. -Transparent proxy also hardens application security by preventing direct inbound connections that bypass the mesh. +This topic describes how to use Consul’s transparent proxy feature, which allows applications to communicate through the service mesh without modifying their configurations. Transparent proxy also hardens application security by preventing direct inbound connections that bypass the mesh. -#### Without Transparent Proxy +## Introduction -![Diagram demonstrating that without transparent proxy, applications must "opt in" to connecting to their dependencies through the mesh](/img/consul-connect/without-transparent-proxy.png) +When transparent proxy is enabled, Consul is able to perform the following actions automatically: -Without transparent proxy, application owners need to: +- Infer the location of upstream services using service intentions. +- Redirect outbound connections that point to KubeDNS through the proxy. +- Force traffic through the proxy to prevent unauthorized direct access to the application. -1. Explicitly configure upstream services, choosing a local port to access them. -1. Change application to access `localhost:`. -1. Configure application to listen only on the loopback interface to prevent unauthorized - traffic from bypassing the mesh. - -#### With Transparent Proxy +The following diagram shows how transparent proxy routes traffic: ![Diagram demonstrating that with transparent proxy, connections are automatically routed through the mesh](/img/consul-connect/with-transparent-proxy.png) -With transparent proxy: +When transparent proxy is disabled, you must manually specify the following configurations so that your applications can communicate with other services in the mesh: -1. Local upstreams are inferred from service intentions and peered upstreams are - inferred from imported services, so no explicit configuration is needed. -1. Outbound connections pointing to a Kubernetes DNS record "just work" — network rules - redirect them through the proxy. -1. Inbound traffic is forced to go through the proxy to prevent unauthorized - direct access to the application. +* Explicitly configure upstream services by specifying a local port to access them. +* Change application to access `localhost:`. +* Configure applications to only listen on the loopback interface to prevent unauthorized traffic from bypassing the mesh. + +The following diagram shows how traffic flows through the mesh without transparent proxy enabled: -#### Overview +![Diagram demonstrating that without transparent proxy, applications must "opt in" to connecting to their dependencies through the mesh](/img/consul-connect/without-transparent-proxy.png) -Transparent proxy allows users to reach other services in the service mesh while ensuring that inbound and outbound -traffic for services in the mesh are directed through the sidecar proxy. Traffic is secured -and only reaches intended destinations since the proxy can enforce security and policy like TLS and Service Intentions. +Transparent proxy is available for Kubernetes environments. As part of the integration with Kubernetes, Consul registers Kubernetes Services, injects sidecar proxies, and enables traffic redirection. -Previously, service mesh users would need to explicitly define upstreams for a service as a local listener on the sidecar -proxy, and dial the local listener to reach the appropriate upstream. Users would also have to set intentions to allow -specific services to talk to one another. Transparent proxying reduces this duplication, by determining upstreams -implicitly from Service Intentions and imported services from a peer. Explicit upstreams are still supported in the [proxy service -registration](/docs/connect/registration/service-registration) on VMs and via the -[annotation](/docs/k8s/annotations-and-labels#consul-hashicorp-com-connect-service-upstreams) in Kubernetes. +## Requirements -To support transparent proxying, Consul's CLI now has a command -[`consul connect redirect-traffic`](/commands/connect/redirect-traffic) to redirect traffic through an inbound and -outbound listener on the sidecar. Consul also watches Service Intentions and imported services then configures the Envoy -proxy with the appropriate upstream IPs. If the default ACL policy is "allow", then Service Intentions are not required. -In Consul on Kubernetes, the traffic redirection command is automatically set up via an init container. +Your network must meet the following environment and software requirements to use transparent proxy. -## Prerequisites +* Transparent proxy is available for Kubernetes environments. +* Consul 1.10.0+ +* Consul Helm chart 0.32.0+. If you want to use the Consul CNI plugin to redirect traffic, Helm chart 0.48.0+ is required. Refer to [Enable the Consul CNI plugin](#enable-the-consul-cni-plugin) for additional information. +* [Service intentions](/docs/connect/intentions) must be configured to allow communication between intended services. +* The `ip_tables` kernel module must be running on all worker nodes within a Kubernetes cluster. If you are using the `modprobe` Linux utility, for example, issue the following command: -### Kubernetes + `$ modprobe ip_tables` -* To use transparent proxy on Kubernetes, Consul-helm >= `0.32.0` and Consul-k8s >= `0.26.0` are required in addition to Consul >= `1.10.0`. -* If the default policy for ACLs is "deny", then Service Intentions should be set up to allow intended services to connect to each other. -Otherwise, all Connect services can talk to all other services. -* If using Transparent Proxy, all worker nodes within a Kubernetes cluster must have the `ip_tables` kernel module running, e.g. `modprobe ip_tables`. - -The Kubernetes integration takes care of registering Kubernetes services with Consul, injecting a sidecar proxy, and -enabling traffic redirection. - -## Upgrading to Transparent Proxy - -~> When upgrading from older versions (i.e Consul-k8s < `0.26.0` or Consul-helm < `0.32.0`) to Consul-k8s >= `0.26.0` and Consul-helm >= `0.32.0`, please make sure to follow the upgrade steps [here](/docs/upgrading/upgrade-specific/#transparent-proxy-on-kubernetes). +~> **Upgrading to a supported version**: Always follow the [proper upgrade path](/docs/upgrading/upgrade-specific/#transparent-proxy-on-kubernetes) when upgrading to a supported version of Consul, Consul on Kubernetes (`consul-k8s`), and the Consul Helm chart. ## Configuration -### Enabling Transparent Proxy -Transparent proxy can be enabled in Kubernetes on the whole cluster via the Helm value: +This section describes how to configure the transparent proxy. + +### Enable transparent proxy + +You can enable the transparent proxy for an entire cluster, individual Kubernetes namespaces, and individual services. + +When you install Consul using the Helm chart, transparent proxy is enabled for the entire cluster by default. + +#### Entire cluster + +Use the `connectInject.transparentProxy.defaultEnabled` Helm value to enable or disable transparent proxy for the entire cluster: ```yaml connectInject: @@ -82,15 +69,16 @@ connectInject: defaultEnabled: true ``` -It can also be enabled on a per namespace basis by setting the label `consul.hashicorp.com/transparent-proxy=true` on the -Kubernetes namespace. This will override the Helm value `connectInject.transparentProxy.defaultEnabled` and define the -default behavior of Pods in the namespace. For example: +#### Kubernetes namespace + +Apply the `consul.hashicorp.com/transparent-proxy=true` label to enable transparent proxy for a Kubernetes namespace. The label overrides the `connectInject.transparentProxy.defaultEnabled` Helm value and defines the default behavior of Pods in the namespace. The following example enables transparent proxy for Pods in the `my-app` namespace: + ```bash kubectl label namespaces my-app "consul.hashicorp.com/transparent-proxy=true" ``` +#### Individual service -It can also be enabled on a per service basis via the annotation `consul.hashicorp.com/transparent-proxy=true` on the -Pod for each service, which will override both the Helm value and the namespace label: +Apply the `consul.hashicorp.com/transparent-proxy=true` annotation to eanble transparent proxy on the Pod for each service. The annotation overrides the Helm value and the namespace label. The following example enables transparent proxy for the `static-server` service: ```yaml apiVersion: v1 @@ -140,78 +128,136 @@ spec: serviceAccountName: static-server ``` -### Kubernetes HTTP Health Probes Configuration -Traffic redirection interferes with [Kubernetes HTTP health -probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/) since the -probes expect that kubelet can directly reach the application container on the probe's endpoint, but that traffic will -be redirected through the sidecar proxy, causing errors because kubelet itself is not encrypting that traffic using a -mesh proxy. For this reason, Consul allows you to [overwrite Kubernetes HTTP health probes](/docs/k8s/connect/health) to point to the proxy instead. -This can be done using the Helm value `connectInject.transparentProxy.defaultOverwriteProbes` -or the Pod annotation `consul.hashicorp.com/transparent-proxy-overwrite-probes`. +### Enable the Consul CNI plugin -### Traffic Redirection Configuration -Pods with transparent proxy enabled will have an init container injected that sets up traffic redirection for all -inbound and outbound traffic through the sidecar proxies. This will include all traffic by default, with the ability to -configure exceptions on a per-Pod basis. The following Pod annotations allow you to exclude certain traffic from redirection to the sidecar proxies: +By default, Consul generates a `connect-inject init` container as part of the Kubernetes Pod startup process. The container configures traffic redirection in the service mesh through the sidecar proxy. To configure redirection, the container requires elevated CAP_NET_ADMIN privileges, which may not be compatible with security policies in your organization. -- [`consul.hashicorp.com/transparent-proxy-exclude-inbound-ports`](/docs/k8s/annotations-and-labels#consul-hashicorp-com-transparent-proxy-exclude-inbound-ports) -- [`consul.hashicorp.com/transparent-proxy-exclude-outbound-ports`](/docs/k8s/annotations-and-labels#consul-hashicorp-com-transparent-proxy-exclude-outbound-ports) -- [`consul.hashicorp.com/transparent-proxy-exclude-outbound-cidrs`](/docs/k8s/annotations-and-labels#consul-hashicorp-com-transparent-proxy-exclude-outbound-cidrs) -- [`consul.hashicorp.com/transparent-proxy-exclude-uids`](/docs/k8s/annotations-and-labels#consul-hashicorp-com-transparent-proxy-exclude-uids) +Instead, you can enable the Consul container network interface (CNI) plugin to perform traffic redirection. Because the plugin is executed by the Kubernetes kubelet, it already has the elevated privileges necessary to configure the network. Additionally, you do not need to specify annotations that automatically overwrite Kubernetes HTTP health probes when the plugin is enabled (see [Overwrite Kubernetes HTTP health probes](#overwrite-kubernetes-http-health-probes)). +The Consul Helm chart installs the CNI plugin, but it is disabled by default. Refer to the [instructions for enabling the CNI plugin](/docs/k8s/installation/install#enable-the-consul-cni-plugin) in the Consul on Kubernetes installation documentation for additional information. -### Dialing Services Across Kubernetes Clusters +### Traffic redirection -- You cannot use transparent proxy in a deployment configuration with [federation between Kubernetes clusters](/docs/k8s/installation/multi-cluster/kubernetes). - Instead, services in one Kubernetes cluster must explicitly dial a service to a Consul datacenter in another Kubernetes cluster using the - [consul.hashicorp.com/connect-service-upstreams](/docs/k8s/annotations-and-labels#consul-hashicorp-com-connect-service-upstreams) - annotation. For example, an annotation of - `"consul.hashicorp.com/connect-service-upstreams": "my-service:1234:dc2"` reaches an upstream service called `my-service` - in the datacenter `dc2` on port `1234`. +There are two mechanisms for redirecting traffic through the sidecar proxies. By default, Consul injects an init container that redirects all inbound and outbound traffic. The default mechanism requires elevated permissions (CAP_NET_ADMIN) in order to redirect traffic to the service mesh. -- You cannot use transparent proxy in a deployment configuration with a - [single Consul datacenter spanning multiple Kubernetes clusters](/docs/k8s/installation/deployment-configurations/single-dc-multi-k8s). Instead, - services in one Kubernetes cluster must explicitly dial a service in another Kubernetes cluster using the - [consul.hashicorp.com/connect-service-upstreams](/docs/k8s/annotations-and-labels#consul-hashicorp-com-connect-service-upstreams) - annotation. For example, an annotation of - `"consul.hashicorp.com/connect-service-upstreams": "my-service:1234"`, - reaches an upstream service called `my-service` in another Kubernetes cluster and on port `1234`. - Although transparent proxy is enabled, Kubernetes DNS is not utilized when communicating between services that exist on separate Kubernetes clusters. +Alternatively, you can enable the Consul CNI plugin to handle traffic redirection. Because the Kubernetes kubelet runs CNI plugins, the Consul CNI plugin has the necessary privileges to apply routing tables in the network. -- In a deployment configuration with [cluster peering](/docs/connect/cluster-peering), - transparent proxy is fully supported and thus dialing services explicitly is not required. +Both mechanisms redirect all inbound and outbound traffic, but you can configure exceptions for specific Pods or groups of Pods. The following annotations enable you to exclude certain traffic from being redirected to sidecar proxies. +#### Exclude inbound ports -## Known Limitations +The [`consul.hashicorp.com/transparent-proxy-exclude-inbound-ports`](/docs/k8s/annotations-and-labels#consul-hashicorp-com-transparent-proxy-exclude-inbound-ports) annotation defines a comma-separated list of inbound ports to exclude from traffic redirection when running in transparent proxy mode. The port numbers are string data values. In the following example, services in the pod at port `8200` and `8201` are not redirected through the transparent proxy: -- Deployment configurations with federation across or a single datacenter spanning multiple clusters must explicitly dial a - service in another datacenter or cluster using annotations. + -- When dialing headless services, the request is proxied using a plain TCP proxy. The upstream's protocol is not considered. +```yaml +"metadata": { + "annotations": { + "consul.hashicorp.com/transparent-proxy-exclude-inbound-ports" : "8200, 8201” + } +} +``` + -## Using Transparent Proxy +#### Exclude outbound ports -In Kubernetes, services can reach other services via their -[Kubernetes DNS](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/) address or through Pod IPs, and that -traffic will be transparently sent through the proxy. Connect services in Kubernetes are required to have a Kubernetes -service selecting the Pods. +The [`consul.hashicorp.com/transparent-proxy-exclude-outbound-ports`](/docs/k8s/annotations-and-labels#consul-hashicorp-com-transparent-proxy-exclude-outbound-ports) annotation defines a comma-separated list of outbound ports to exclude from traffic redirection when running in transparent proxy mode. The port numbers are string data values. In the following example, services in the pod at port `8200` and `8201` are not redirected through the transparent proxy: -~> **Note**: In order to use Kubernetes DNS, the Kubernetes service name needs to match the Consul service name. This is the -case by default, unless the service Pods have the annotation `consul.hashicorp.com/connect-service` overriding the -Consul service name. + -Transparent proxy is enabled by default in Consul-helm >=`0.32.0`. The Helm value used to enable/disable transparent -proxy for all applications in a Kubernetes cluster is `connectInject.transparentProxy.defaultEnabled`. +```yaml +"metadata": { + "annotations": { + "consul.hashicorp.com/transparent-proxy-exclude-outbound-ports" : "8200, 8201” + } +} +``` -Each Pod for the service will be configured with iptables rules to direct all inbound and outbound traffic through an -inbound and outbound listener on the sidecar proxy. The proxy will be configured to know how to route traffic to the -appropriate upstream services based on [Service -Intentions](/docs/connect/config-entries/service-intentions). This means Connect services no longer -need to use the `consul.hashicorp.com/connect-service-upstreams` annotation to configure upstreams explicitly. Once the -Service Intentions are set, they can simply address the upstream services using Kubernetes DNS. + -As of Consul-k8s >= `0.26.0` and Consul-helm >= `0.32.0`, a Kubernetes service that selects application pods is required -for Connect applications, i.e: +#### Exclude outbound CIDR blocks + +The [`consul.hashicorp.com/transparent-proxy-exclude-outbound-cidrs`](/docs/k8s/annotations-and-labels#consul-hashicorp-com-transparent-proxy-exclude-outbound-cidrs) annotation +defines a comma-separated list of outbound CIDR blocks to exclude from traffic redirection when running in transparent proxy mode. The CIDR blocks are string data values. +In the following example, services in the `3.3.3.3/24` IP range are not redirected through the transparent proxy: + + + +```yaml +"metadata": { + "annotations": { + "consul.hashicorp.com/transparent-proxy-exclude-outbound-cidrs" : "3.3.3.3,3.3.3.3/24" + } +} +``` + + +#### Exclude user IDs + +The [`consul.hashicorp.com/transparent-proxy-exclude-uids`](/docs/k8s/annotations-and-labels#consul-hashicorp-com-transparent-proxy-exclude-uids) annotation +defines a comma-separated list of additional user IDs to exclude from traffic redirection when running in transparent proxy mode. The user IDs are string data values. +In the following example, services with the IDs `4444 ` and `44444 ` are not redirected through the transparent proxy: + + + +```yaml +"metadata": { + "annotations": { + "consul.hashicorp.com/transparent-proxy-exclude-uids" : "4444,44444” + } +} +``` + + + +### Kubernetes HTTP health probes configuration + +By default, `connect-inject` is disabled. As a result, Consul on Kubernetes uses a mechanism for traffic redirection that interferes with [Kubernetes HTTP health +probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/). This is because probes expect the kubelet to reach the application container on the probe's endpoint. Instead, traffic is redirected through the sidecar proxy. As a result, health probes return errors because the kubelet does not encrypt that traffic using a mesh proxy. + +There are two methods for solving this issue. The first method is to set the `connectInject.transparentProxy.defaultOverwriteProbes` annotation to overwrite the Kubernetes HTTP health probes so that they point to the proxy. The second method is to [enable the Consul container network interface (CNI) plugin](#enable-the-consul-cni-plugin) to perform traffic redirection. Refer to the [Consul on Kubernetes installation instructions](/docs/k8s/installation/install) for additional information. + +#### Overwrite Kubernetes HTTP health probes + +You can either include the `connectInject.transparentProxy.defaultOverwriteProbes` Helm value to your command or add the `consul.hashicorp.com/transparent-proxy-overwrite-probes` Kubernetes annotation to your pod configuration to overwrite health probes. + +Refer to [Kubernetes Health Checks in Consul on Kubernetes](/docs/k8s/connect/health) for additional information. + +### Dial services across Kubernetes cluster + +If your [Consul servers are federated between Kubernetes clusters](/docs/k8s/installation/multi-cluster/kubernetes), +then you must configure services in one Kubernetes cluster to explicitly dial a service in the datacenter of another Kubernetes cluster using the +[consul.hashicorp.com/connect-service-upstreams](/docs/k8s/annotations-and-labels#consul-hashicorp-com-connect-service-upstreams) annotation. +The following example configures the service to dial an upstream service called `my-service` in datacenter `dc2` on port `1234`: + +```yaml + "consul.hashicorp.com/connect-service-upstreams": "my-service:1234:dc2" +``` + +If your Consul cluster is deployed to a [single datacenter spanning multiple Kubernetes clusters](/docs/k8s/installation/deployment-configurations/single-dc-multi-k8s), +then you must configure services in one Kubernetes cluster to explicitly dial a service in another Kubernetes cluster using the +[consul.hashicorp.com/connect-service-upstreams](/docs/k8s/annotations-and-labels#consul-hashicorp-com-connect-service-upstreams) annotation. +The following example configures the service to dial an upstream service called `my-service` in another Kubernetes cluster on port `1234`: + +```yaml +"consul.hashicorp.com/connect-service-upstreams": "my-service:1234" +``` + +You do not need to configure services to explicitlly dial upstream services if your Consul clusters are connected with a [peering connection](/docs/connect/cluster-peering). + +## Usage + +When transparent proxy is enabled, traffic sent to [KubeDNS](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/) +or Pod IP addresses is redirected through the proxy. You must use a selector to bind Kubernetes Services to Pods as you define Kubernetes Services in the mesh. +The Kubernetes Service name must match the Consul service name to use KubeDNS. This is the default behavior unless you have applied the `consul.hashicorp.com/connect-service` +Kubernetes annotation to the service pods. The annotation overrides the Consul service name. + +Consul configures redirection for each Pod bound to the Kubernetes Service using `iptables` rules. The rules redirect all inbound and outbound traffic through an inbound and outbound listener on the sidecar proxy. Consul configures the proxy to route traffic to the appropriate upstream services based on [service +intentions](/docs/connect/config-entries/service-intentions), which address the upstream services using KubeDNS. + +In the following example, the Kubernetes service selects `sample-app` application Pods so that they can be reached within the mesh. + + ```yaml apiVersion: v1 @@ -227,22 +273,17 @@ spec: port: 80 ``` -In the example above, if another service wants to reach `sample-app` via transparent proxying, -it can dial `sample-app.default.svc.cluster.local`, using -[Kubernetes DNS](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/). -If ACLs with default "deny" policy are enabled, it also needs a -[ServiceIntention](/docs/connect/config-entries/service-intentions) allowing it to talk to -`sample-app`. + + +Additional services can query the [KubeDNS](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/) at `sample-app.default.svc.cluster.local` to reach `sample-app`. If ACLs are enabled and configured with default `deny` policies, the configuration also requires a [`ServiceIntention`](/docs/connect/config-entries/service-intentions) to allow it to talk to `sample-app`. ### Headless Services -For services that are not addressed using a virtual cluster IP, the upstream service must be -configured using the [DialedDirectly](/docs/connect/config-entries/service-defaults#dialeddirectly) -option. +For services that are not addressed using a virtual cluster IP, you must configure the upstream service using the [DialedDirectly](/docs/connect/config-entries/service-defaults#dialeddirectly) option. Then, use DNS to discover individual instance addresses and dial them through the transparent proxy. When this mode is enabled on the upstream, services present connect certificates for mTLS and intentions are enforced at the destination. -Individual instance addresses can then be discovered using DNS, and dialed through the transparent proxy. -When this mode is enabled on the upstream, connect certificates will be presented for mTLS and -intentions will be enforced at the destination. +Note that when dialing individual instances, Consul ignores the HTTP routing rules configured with configuration entries. The transparent proxy acts as a TCP proxy to the original destination IP address. -Note that when dialing individual instances HTTP routing rules configured with config entries -will **not** be considered. The transparent proxy acts as a TCP proxy to the original -destination IP address. +## Known Limitations + +- Deployment configurations with federation across or a single datacenter spanning multiple clusters must explicitly dial a service in another datacenter or cluster using annotations. + +- When dialing headless services, the request is proxied using a plain TCP proxy. Consul does not take into consideration the upstream's protocol. diff --git a/website/content/docs/k8s/installation/deployment-configurations/clients-outside-kubernetes.mdx b/website/content/docs/k8s/deployment-configurations/clients-outside-kubernetes.mdx similarity index 100% rename from website/content/docs/k8s/installation/deployment-configurations/clients-outside-kubernetes.mdx rename to website/content/docs/k8s/deployment-configurations/clients-outside-kubernetes.mdx diff --git a/website/content/docs/k8s/installation/deployment-configurations/consul-enterprise.mdx b/website/content/docs/k8s/deployment-configurations/consul-enterprise.mdx similarity index 100% rename from website/content/docs/k8s/installation/deployment-configurations/consul-enterprise.mdx rename to website/content/docs/k8s/deployment-configurations/consul-enterprise.mdx diff --git a/website/content/docs/k8s/installation/multi-cluster/index.mdx b/website/content/docs/k8s/deployment-configurations/multi-cluster/index.mdx similarity index 100% rename from website/content/docs/k8s/installation/multi-cluster/index.mdx rename to website/content/docs/k8s/deployment-configurations/multi-cluster/index.mdx diff --git a/website/content/docs/k8s/installation/multi-cluster/kubernetes.mdx b/website/content/docs/k8s/deployment-configurations/multi-cluster/kubernetes.mdx similarity index 100% rename from website/content/docs/k8s/installation/multi-cluster/kubernetes.mdx rename to website/content/docs/k8s/deployment-configurations/multi-cluster/kubernetes.mdx diff --git a/website/content/docs/k8s/installation/multi-cluster/vms-and-kubernetes.mdx b/website/content/docs/k8s/deployment-configurations/multi-cluster/vms-and-kubernetes.mdx similarity index 100% rename from website/content/docs/k8s/installation/multi-cluster/vms-and-kubernetes.mdx rename to website/content/docs/k8s/deployment-configurations/multi-cluster/vms-and-kubernetes.mdx diff --git a/website/content/docs/k8s/installation/deployment-configurations/servers-outside-kubernetes.mdx b/website/content/docs/k8s/deployment-configurations/servers-outside-kubernetes.mdx similarity index 100% rename from website/content/docs/k8s/installation/deployment-configurations/servers-outside-kubernetes.mdx rename to website/content/docs/k8s/deployment-configurations/servers-outside-kubernetes.mdx diff --git a/website/content/docs/k8s/installation/deployment-configurations/single-dc-multi-k8s.mdx b/website/content/docs/k8s/deployment-configurations/single-dc-multi-k8s.mdx similarity index 100% rename from website/content/docs/k8s/installation/deployment-configurations/single-dc-multi-k8s.mdx rename to website/content/docs/k8s/deployment-configurations/single-dc-multi-k8s.mdx diff --git a/website/content/docs/k8s/installation/vault/data-integration/bootstrap-token.mdx b/website/content/docs/k8s/deployment-configurations/vault/data-integration/bootstrap-token.mdx similarity index 100% rename from website/content/docs/k8s/installation/vault/data-integration/bootstrap-token.mdx rename to website/content/docs/k8s/deployment-configurations/vault/data-integration/bootstrap-token.mdx diff --git a/website/content/docs/k8s/installation/vault/data-integration/connect-ca.mdx b/website/content/docs/k8s/deployment-configurations/vault/data-integration/connect-ca.mdx similarity index 100% rename from website/content/docs/k8s/installation/vault/data-integration/connect-ca.mdx rename to website/content/docs/k8s/deployment-configurations/vault/data-integration/connect-ca.mdx diff --git a/website/content/docs/k8s/installation/vault/data-integration/enterprise-license.mdx b/website/content/docs/k8s/deployment-configurations/vault/data-integration/enterprise-license.mdx similarity index 100% rename from website/content/docs/k8s/installation/vault/data-integration/enterprise-license.mdx rename to website/content/docs/k8s/deployment-configurations/vault/data-integration/enterprise-license.mdx diff --git a/website/content/docs/k8s/installation/vault/data-integration/gossip.mdx b/website/content/docs/k8s/deployment-configurations/vault/data-integration/gossip.mdx similarity index 100% rename from website/content/docs/k8s/installation/vault/data-integration/gossip.mdx rename to website/content/docs/k8s/deployment-configurations/vault/data-integration/gossip.mdx diff --git a/website/content/docs/k8s/installation/vault/data-integration/index.mdx b/website/content/docs/k8s/deployment-configurations/vault/data-integration/index.mdx similarity index 100% rename from website/content/docs/k8s/installation/vault/data-integration/index.mdx rename to website/content/docs/k8s/deployment-configurations/vault/data-integration/index.mdx diff --git a/website/content/docs/k8s/installation/vault/data-integration/partition-token.mdx b/website/content/docs/k8s/deployment-configurations/vault/data-integration/partition-token.mdx similarity index 100% rename from website/content/docs/k8s/installation/vault/data-integration/partition-token.mdx rename to website/content/docs/k8s/deployment-configurations/vault/data-integration/partition-token.mdx diff --git a/website/content/docs/k8s/installation/vault/data-integration/replication-token.mdx b/website/content/docs/k8s/deployment-configurations/vault/data-integration/replication-token.mdx similarity index 100% rename from website/content/docs/k8s/installation/vault/data-integration/replication-token.mdx rename to website/content/docs/k8s/deployment-configurations/vault/data-integration/replication-token.mdx diff --git a/website/content/docs/k8s/installation/vault/data-integration/server-tls.mdx b/website/content/docs/k8s/deployment-configurations/vault/data-integration/server-tls.mdx similarity index 100% rename from website/content/docs/k8s/installation/vault/data-integration/server-tls.mdx rename to website/content/docs/k8s/deployment-configurations/vault/data-integration/server-tls.mdx diff --git a/website/content/docs/k8s/installation/vault/data-integration/snapshot-agent-config.mdx b/website/content/docs/k8s/deployment-configurations/vault/data-integration/snapshot-agent-config.mdx similarity index 100% rename from website/content/docs/k8s/installation/vault/data-integration/snapshot-agent-config.mdx rename to website/content/docs/k8s/deployment-configurations/vault/data-integration/snapshot-agent-config.mdx diff --git a/website/content/docs/k8s/installation/vault/data-integration/webhook-certs.mdx b/website/content/docs/k8s/deployment-configurations/vault/data-integration/webhook-certs.mdx similarity index 100% rename from website/content/docs/k8s/installation/vault/data-integration/webhook-certs.mdx rename to website/content/docs/k8s/deployment-configurations/vault/data-integration/webhook-certs.mdx diff --git a/website/content/docs/k8s/installation/vault/index.mdx b/website/content/docs/k8s/deployment-configurations/vault/index.mdx similarity index 100% rename from website/content/docs/k8s/installation/vault/index.mdx rename to website/content/docs/k8s/deployment-configurations/vault/index.mdx diff --git a/website/content/docs/k8s/installation/vault/systems-integration.mdx b/website/content/docs/k8s/deployment-configurations/vault/systems-integration.mdx similarity index 100% rename from website/content/docs/k8s/installation/vault/systems-integration.mdx rename to website/content/docs/k8s/deployment-configurations/vault/systems-integration.mdx diff --git a/website/content/docs/k8s/installation/vault/wan-federation.mdx b/website/content/docs/k8s/deployment-configurations/vault/wan-federation.mdx similarity index 100% rename from website/content/docs/k8s/installation/vault/wan-federation.mdx rename to website/content/docs/k8s/deployment-configurations/vault/wan-federation.mdx diff --git a/website/content/docs/k8s/installation/install-cli.mdx b/website/content/docs/k8s/installation/install-cli.mdx index 4cd3ea9f55..ae6de69bf7 100644 --- a/website/content/docs/k8s/installation/install-cli.mdx +++ b/website/content/docs/k8s/installation/install-cli.mdx @@ -1,23 +1,43 @@ --- layout: docs -page_title: Installing the Consul K8s CLI +page_title: Install Consul from the Consul K8s CLI description: >- - Consul K8s CLI is a tool for quickly installing and interacting with Consul on Kubernetes. + This topic describes how to install Consul on Kubernetes using the Consul K8s CLI tool. --- -# Installing the Consul K8s CLI -Consul K8s CLI is a tool for quickly installing and interacting with Consul on Kubernetes. Ensure that you are installing the correct version of the CLI for your Consul on Kubernetes deployment, as the CLI and the control plane are version dependent. +# Install Consul on Kubernetes from Consul K8s CLI + +This topic describes how to install Consul on Kubernetes using the Consul K8s CLI tool. The Consul K8s CLI tool enables you to quickly install and interact with Consul on Kubernetes. Use the Consul K8s CLI tool to install Consul on Kubernetes if you are deploying a single cluster. We recommend using the [Helm chart installation method](/docs/k8s/installation/install) if you are installing Consul on Kubernetes for multi-cluster deployments that involve cross-partition or cross datacenter communication. + +## Introduction + +If it is your first time installing Consul on Kubernetes, then you must first install the Consul K8s CLI tool. You can install Consul on Kubernetes using the Consul K8s tool after installing the CLI. + +## Requirements + +- The `kubectl` client must already be configured to authenticate to the Kubernetes cluster using a valid `kubeconfig` file. +- Install one of the following package managers so that you can install the Consul K8s CLI tool. The installation instructions also provide commands for installing and using the package managers: + - MacOS: [Homebrew](https://brew.sh) + - Ubuntu/Debian: apt + - CentOS/RHEL: yum + +You must install the correct version of the CLI for your Consul on Kubernetes deployment. To deploy a previous version of Consul on Kubernetes, download the specific version of the CLI that matches the version of the control plane that you would like to deploy. Refer to the [compatibility matrix](/docs/k8s/compatibility) for details. + ## Install the CLI -These instructions describe how to install the latest version of the CLI depending on your Operating System, and are suited for fresh installations of Consul on Kubernetes. +The following instructions describe how to install the latest version of the Consul K8s CLI tool, as well as earlier versions, so that you can install an appropriate version of tool for your control plane. + +### Install the latest version + +Complete the following instructions for a fresh installation of Consul on Kubernetes. -The [Homebrew](https://brew.sh) package manager is required to complete the following installation instructions. The Homebrew formulae will always install the latest version of a binary. If you are looking to install a specific version of the CLI please follow [Install a specific version of Consul K8s CLI](#install-a-specific-version-of-the-cli). +The [Homebrew](https://brew.sh) package manager is required to complete the following installation instructions. The Homebrew formulae always installs the latest version of a binary. 1. Install the HashiCorp `tap`, which is a repository of all Homebrew packages for HashiCorp: ```shell-session @@ -104,17 +124,15 @@ The [Homebrew](https://brew.sh) package manager is required to complete the foll -## Install a specific version of the CLI +### Install a previous version -These instructions describe how to install a specific version of the CLI and are best suited for installing or managing specific versions of the Consul on Kubernetes control plane. +Complete the following instructions to install a specific version of the CLI so that your tool is compatible with your Consul on Kubernetes control plane. Refer to the [compatibility matrix](/docs/k8s/compatibility) for additional information. -Homebrew does not provide a method to install previous versions of a package. The Consul K8s CLI will need to be installed manually. Previous versions of the Consul K8s CLI could be used to install a specific version of Consul on the Kubernetes control plane. Manual upgrades to the Consul K8s CLI is also performed in the same manner, provided that the Consul K8s CLI was manually installed before. - -1. Download the desired Consul K8s CLI using the following `curl` command. Enter the appropriate version for your deployment via the `$VERSION` environment variable. +1. Download the appropriate version of Consul K8s CLI using the following `curl` command. Set the `$VERSION` environment variable to the appropriate version for your deployment. ```shell-session $ export VERSION=0.39.0 && \ @@ -203,3 +221,61 @@ Homebrew does not provide a method to install previous versions of a package. Th + +## Install Consul on Kubernetes + +After installing the Consul K8s CLI tool (`consul-k8s`), issue the `install` subcommand and any additional options to install Consul on Kubernetes. Refer to the [Consul K8s CLI reference](/docs/k8s/k8s-cli) for details about all commands and available options. If you do not include any additional options, the `consul-k8s` CLI installs Consul on Kubernetes using the default settings form the Consul Helm chart values. The following example installs Consul on Kubernetes with service mesh and CRDs enabled. + +```shell-session +$ consul-k8s install -set connectInject.enabled=true -set controller.enabled=true + +==> Pre-Install Checks +No existing installations found. + ✓ No previous persistent volume claims found + ✓ No previous secrets found +==> Consul Installation Summary + Installation name: consul + Namespace: consul + Overrides: + connectInject: + enabled: true + controller: + enabled: true + + Proceed with installation? (y/N) y + +==> Running Installation + ✓ Downloaded charts +--> creating 1 resource(s) +--> creating 45 resource(s) +--> beginning wait for 45 resources with timeout of 10m0s + ✓ Consul installed into namespace "consul" +``` + +You can include the `-auto-approve` option set to `true` to proceed with the installation if the pre-install checks pass. + +The pre-install checks may fail if existing `PersistentVolumeClaims` (PVC) are detected. Refer to the [uninstall instructions](/docs/k8s/operations/uninstall#uninstall-consul) for information about removing PVCs. + +## Check the Consul cluster status + +Issue the `consul-k8s status` command to view the status of the installed Consul cluster. + +```shell-session +$ consul-k8s status + +==> Consul-K8s Status Summary + NAME | NAMESPACE | STATUS | CHARTVERSION | APPVERSION | REVISION | LAST UPDATED +---------+-----------+----------+--------------+------------+----------+-------------------------- + consul | consul | deployed | 0.40.0 | 1.11.2 | 1 | 2022/01/31 16:58:51 PST + +==> Config: + connectInject: + enabled: true + controller: + enabled: true + global: + name: consul + +✓ Consul servers healthy (3/3) +✓ Consul clients healthy (3/3) +``` \ No newline at end of file diff --git a/website/content/docs/k8s/installation/install.mdx b/website/content/docs/k8s/installation/install.mdx index ffed47349c..7247013d67 100644 --- a/website/content/docs/k8s/installation/install.mdx +++ b/website/content/docs/k8s/installation/install.mdx @@ -1,133 +1,37 @@ --- layout: docs -page_title: Installing Consul on Kubernetes +page_title: Install Consul on Kubernetes from the Helm Chart description: >- - Consul can run directly on Kubernetes, both in server or client mode. For - pure-Kubernetes workloads, this enables Consul to also exist purely within - Kubernetes. For heterogeneous workloads, Consul agents can join a server - running inside or outside of Kubernetes. + This topic describes how to install Consul on Kubernetes using the official Consul Helm chart. --- -# Installing Consul on Kubernetes +# Install Consul on Kubernetes from the Helm Chart -Consul can run directly on Kubernetes, both in server or client mode. -For pure-Kubernetes workloads, this enables Consul to also exist purely -within Kubernetes. For heterogeneous workloads, Consul agents can join -a server running inside or outside of Kubernetes. +This topic describes how to install Consul on Kubernetes using the official Consul Helm chart. For instruction on how to install Consul on Kubernetes using the Consul K8s CLI, refer to [Installing the Consul K8s CLI](/docs/k8s/installation/install-cli). -You can install Consul on Kubernetes using the following methods: +## Introduction -1. [Consul K8s CLI install](#consul-k8s-cli-installation) -1. [Helm chart install](#helm-chart-installation) +We recommend using the Consul Helm chart to install Consul on Kubernetes for multi-cluster installations that involve cross-partition or cross datacenter communication. The Helm chart installs and configures all necessary components to run Consul. The configuration enables you to run a server cluster, a client cluster, or both. + +Consul can run directly on Kubernetes in server or client mode so that you can leverage Consul functionality if your workloads are fully deployed to Kubernetes. For heterogeneous workloads, Consul agents can join a server running inside or outside of Kubernetes. Refer to the [architecture section](/docs/k8s/architecture) to learn more about the general architecture of Consul on Kubernetes. + +The Helm chart exposes several useful configurations and automatically sets up complex resources, but it does not automatically operate Consul. You must still become familiar with how to monitor, backup, and upgrade the Consul cluster. + +The Helm chart has no required configuration, so it installs a Consul cluster with default configurations. We strongly recommend that you [learn about the configuration options](/docs/k8s/helm#configuration-values) prior to going to production. + +-> **Security warning**: By default, Helm installs Consul with security configurations disabled so that the out-of-box experience is optimized for new users. We strongly recommend using a properly-secured Kubernetes cluster or making sure that you understand and enable [Consul’s security features](/docs/security) before going into production. Some security features are not supported in the Helm chart and require additional manual configuration. Refer to the [architecture](/docs/k8s/installation/install#architecture) section to learn more about the general architecture of Consul on Kubernetes. + For a hands-on experience with Consul as a service mesh for Kubernetes, follow the [Getting Started with Consul service mesh](https://learn.hashicorp.com/tutorials/consul/service-mesh-deploy?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial. -## Consul K8s CLI Installation +## Requirements -We recommend using the [Consul K8s CLI](/docs/k8s/k8s-cli) to install Consul on Kubernetes for single-cluster deployments. You can install Consul on Kubernetes using the Consul K8s CLI tool after installing the CLI. +- Helm version 3.2+. Visit the [Helm website](https://helm.sh/docs/intro/install/) to download the latest version. -Before beginning the installation process, verify that `kubectl` is already configured to authenticate to the Kubernetes cluster using a valid `kubeconfig` file. - -The [Homebrew](https://brew.sh) package manager is required to complete the following installation instructions. - --> ** NOTE:** To deploy a previous version of Consul on Kubernetes via the CLI, you will need to first download the specific version of the CLI that matches the version of the control plane that you would like to deploy. Please follow [Install a specific version of Consul K8s CLI](/docs/k8s/installation/install-cli#install-a-specific-version-of-the-cli). - -1. Install the HashiCorp `tap`, which is a repository of all Homebrew packages for HashiCorp: - ```shell-session - $ brew tap hashicorp/tap - ``` - -1. Install the Consul K8s CLI with the `hashicorp/tap/consul` formula. - ```shell-session - $ brew install hashicorp/tap/consul-k8s - ``` - -1. Issue the `install` subcommand to install Consul on Kubernetes. Refer to the [Consul K8s CLI reference](/docs/k8s/k8s-cli) for details about all commands and available options. Without any additional options passed, the `consul-k8s` CLI will install Consul on Kubernetes by using the Consul Helm chart's default values. Below is an example that installs Consul on Kubernetes with Service Mesh and CRDs enabled. If you did not set the `-auto-approve` option to `true`, you will be prompted to proceed with the installation if the pre-install checks pass. - - -> The pre-install checks may fail if existing `PersistentVolumeClaims` (PVC) are detected. Refer to the [uninstall instructions](/docs/k8s/operations/uninstall#uninstall-consul) for information about removing PVCs. - - ```shell-session - $ consul-k8s install -set connectInject.enabled=true -set controller.enabled=true - - ==> Pre-Install Checks - No existing installations found. - ✓ No previous persistent volume claims found - ✓ No previous secrets found - - ==> Consul Installation Summary - Installation name: consul - Namespace: consul - Overrides: - connectInject: - enabled: true - controller: - enabled: true - - Proceed with installation? (y/N) y - - ==> Running Installation - ✓ Downloaded charts - --> creating 1 resource(s) - --> creating 45 resource(s) - --> beginning wait for 45 resources with timeout of 10m0s - ✓ Consul installed into namespace "consul" - ``` - -1. (Optional) Issue the `consul-k8s status` command to quickly glance at the status of the installed Consul cluster. - - ```shell-session - $ consul-k8s status - - ==> Consul-K8s Status Summary - NAME | NAMESPACE | STATUS | CHARTVERSION | APPVERSION | REVISION | LAST UPDATED - ---------+-----------+----------+--------------+------------+----------+-------------------------- - consul | consul | deployed | 0.40.0 | 1.11.2 | 1 | 2022/01/31 16:58:51 PST - - ==> Config: - connectInject: - enabled: true - controller: - enabled: true - global: - name: consul - - ✓ Consul servers healthy (3/3) - ✓ Consul clients healthy (3/3) - ``` - -## Helm Chart Installation - -We recommend using the Consul Helm chart to install Consul on Kubernetes for multi-cluster installations that involve cross-partition of cross datacenter communication. The Helm chart installs and configures all necessary components to run Consul. The configuration enables you to run a server cluster, a client cluster, or both. - -Step-by-step tutorials for how to deploy Consul to Kubernetes, please see -our [Deploy to Kubernetes](https://learn.hashicorp.com/collections/consul/kubernetes-deploy) -collection. This collection includes configuration caveats for single-node deployments. - -The Helm chart exposes several useful configurations and automatically -sets up complex resources, but it **does not automatically operate Consul.** -You must still become familiar with how to monitor, backup, -upgrade, etc. the Consul cluster. - -The Helm chart has no required configuration and will install a Consul -cluster with default configurations. We strongly recommend [learning about the configuration options](/docs/k8s/helm#configuration-values) prior to going to production. - -~> **Security Warning:** By default, the chart will install an insecure configuration -of Consul. This provides a less complicated out-of-box experience for new users, -but is not appropriate for a production setup. We strongly recommend using -a properly-secured Kubernetes cluster or making sure that you understand and enable -the [recommended security features](/docs/security). Currently, -some of these features are not supported in the Helm chart and require additional -manual configuration. - -### Prerequisites - -The Consul Helm only supports Helm 3.2+. Install the latest version of the Helm CLI here: -[Installing Helm](https://helm.sh/docs/intro/install/). - -### Installing Consul +## Install Consul 1. Add the HashiCorp Helm Repository: @@ -171,14 +75,14 @@ The Consul Helm only supports Helm 3.2+. Install the latest version of the Helm ``` -### Customizing Your Installation +## Custom installation If you want to customize your installation, create a `config.yaml` file to override the default settings. You can learn what settings are available by running `helm inspect values hashicorp/consul` or by reading the [Helm Chart Reference](/docs/k8s/helm). -#### Minimal `config.yaml` for Consul Service Mesh +### Minimal `config.yaml` for Consul service mesh The minimal settings to enable [Consul Service Mesh]((/docs/k8s/connect)) would be captured in the following `config.yaml` config file: @@ -203,7 +107,59 @@ NAME: consul ... ``` -#### Enable Consul Service Mesh on select namespaces +### Enable the Consul CNI plugin + +By default, Consul generates a `connect-inject init` container as part of the Kubernetes pod startup process when Consul is in [transparent proxy mode](/docs/connect/transparent-proxy). The container configures traffic redirection in the service mesh through the sidecar proxy. To configure redirection, the container requires elevated CAP_NET_ADMIN privileges, which may not be compatible with security policies in your organization. + +Instead, you can enable the Consul container network interface (CNI) plugin to perform traffic redirection. Because the plugin is executed by the Kubernetes kubelet, the plugin already has the elevated privileges necessary to configure the network. + +Add the following configuration to your `config.yaml` file to enable the Consul CNI plugin: + + + + + +```yaml +global: + name: consul +connectInject: + enabled: true + cni: + enabled: true + logLevel: info + cniBinDir: "/opt/cni/bin" + cniNetDir: "/etc/cni/net.d" +``` + + + + +```yaml +global: + name: consul +connectInject: + enabled: true + cni: + enabled: true + logLevel: info + cniBinDir: "/home/kubernetes/bin" + cniNetDir: "/etc/cni/net.d" +``` + + + + + +The following table describes the available CNI plugin options: + +| Option | Description | Default | +| --- | --- | --- | +| `cni.enabled` | Boolean value that enables or disables the CNI plugin. If `true`, the plugin is responsible for redirecting traffic in the service mesh. If `false`, redirection is handled by the `connect-inject init` container. | `false` | +| `cni.logLevel` | String value that specifies the log level for the installer and plugin. You can specify the following values: `info`, `debug`, `error`. | `info` | +| `cni.cniBinDir` | String value that specifies the location on the Kubernetes node where the CNI plugin is installed. | `/opt/cni/bin` | +| `cni.cniNetDir` | String value that specifies the location on the Kubernetes node for storing the CNI configuration. | `/etc/cni/net.d` | + +### Enable Consul service mesh on select namespaces By default, Consul Service Mesh is enabled on almost all namespaces (with the exception of `kube-system` and `local-path-storage`) within a Kubernetes cluster. You can restrict this to a subset of namespaces by specifying a `namespaceSelector` that matches a label attached to each namespace denoting whether to enable Consul service mesh. In order to default to enabling service mesh on select namespaces by label, the `connectInject.default` value must be set to `true`. @@ -239,12 +195,16 @@ NAME: consul ... ``` -#### Updating your Consul on Kubernetes configuration +### Update your Consul on Kubernetes configuration If you've already installed Consul and want to make changes, you'll need to run `helm upgrade`. See [Upgrading](/docs/k8s/upgrade) for more details. -## Viewing the Consul UI +## Usage + +You can view the Consul UI and access the Consul HTTP API after installation. + +### Viewing the Consul UI The Consul UI is enabled by default when using the Helm chart. For security reasons, it isn't exposed via a `LoadBalancer` Service by default so you must @@ -293,14 +253,14 @@ Then paste the token into the UI under the ACLs tab (without the `%`). to retrieve the bootstrap token since secondary datacenters use a separate token with less permissions. -### Exposing the UI via a service +#### Exposing the UI via a service If you want to expose the UI via a Kubernetes Service, configure the [`ui.service` chart values](/docs/k8s/helm#v-ui-service). This service will allow requests to the Consul servers so it should not be open to the world. -## Accessing the Consul HTTP API +### Accessing the Consul HTTP API The Consul HTTP API should be accessed by communicating to the local agent running on the same node. While technically any listening agent (client or diff --git a/website/content/docs/k8s/installation/platforms/self-hosted-kubernetes.mdx b/website/content/docs/k8s/platforms/self-hosted-kubernetes.mdx similarity index 100% rename from website/content/docs/k8s/installation/platforms/self-hosted-kubernetes.mdx rename to website/content/docs/k8s/platforms/self-hosted-kubernetes.mdx diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index cb33486b7a..b89ec40984 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -419,85 +419,53 @@ "title": "Architecture", "path": "k8s/architecture" }, + { - "title": "Get Started", + "title": "Installation", "routes": [ { - "title": "Installing Consul on Kubernetes", - "path": "k8s/installation/install" - }, - { - "title": "Installing Consul K8s CLI", + "title": "Install from Consul K8s CLI", "path": "k8s/installation/install-cli" }, { - "title": "Platform Guides", - "routes": [ - { - "title": "Minikube", - "href": "https://learn.hashicorp.com/tutorials/consul/kubernetes-minikube?utm_source=consul.io&utm_medium=docs&utm_content=k8s&utm_term=mk" - }, - { - "title": "Kind", - "href": "https://learn.hashicorp.com/tutorials/consul/kubernetes-kind?utm_source=consul.io&utm_medium=docs&utm_content=k8s&utm_term=kind" - }, - { - "title": "AKS (Azure)", - "href": "https://learn.hashicorp.com/tutorials/consul/kubernetes-aks-azure?utm_source=consul.io&utm_medium=docs&utm_content=k8s&utm_term=aks" - }, - { - "title": "EKS (AWS)", - "href": "https://learn.hashicorp.com/tutorials/consul/kubernetes-eks-aws?utm_source=consul.io&utm_medium=docs&utm_content=k8s&utm_term=eks" - }, - { - "title": "GKE (Google Cloud)", - "href": "https://learn.hashicorp.com/tutorials/consul/kubernetes-gke-google?utm_source=consul.io&utm_medium=docs&utm_content=k8s&utm_term=gke" - }, - { - "title": "Red Hat OpenShift", - "href": "https://learn.hashicorp.com/tutorials/consul/kubernetes-openshift-red-hat?utm_source=consul.io&utm_medium=docs&utm_content=k8s&utm_term=openshift" - }, - { - "title": "Self Hosted Kubernetes", - "path": "k8s/installation/platforms/self-hosted-kubernetes" - } - ] + "title": "Install from Helm Chart", + "path": "k8s/installation/install" + } + ] + }, + { + "title": "Deployment Configurations", + "routes": [ + { + "title": "Consul Clients Outside Kubernetes", + "path": "k8s/deployment-configurations/clients-outside-kubernetes" }, { - "title": "Deployment Configurations", - "routes": [ - { - "title": "Consul Clients Outside Kubernetes", - "path": "k8s/installation/deployment-configurations/clients-outside-kubernetes" - }, - { - "title": "Consul Servers Outside Kubernetes", - "path": "k8s/installation/deployment-configurations/servers-outside-kubernetes" - }, - { - "title": "Single Consul Datacenter in Multiple Kubernetes Clusters", - "path": "k8s/installation/deployment-configurations/single-dc-multi-k8s" - }, - { - "title": "Consul Enterprise", - "path": "k8s/installation/deployment-configurations/consul-enterprise" - } - ] + "title": "Consul Servers Outside Kubernetes", + "path": "k8s/deployment-configurations/servers-outside-kubernetes" + }, + { + "title": "Single Consul Datacenter in Multiple Kubernetes Clusters", + "path": "k8s/deployment-configurations/single-dc-multi-k8s" + }, + { + "title": "Consul Enterprise", + "path": "k8s/deployment-configurations/consul-enterprise" }, { "title": "Multi-Cluster Federation", "routes": [ { "title": "Overview", - "path": "k8s/installation/multi-cluster" + "path": "k8s/deployment-configurations/multi-cluster" }, { "title": "Federation Between Kubernetes Clusters", - "path": "k8s/installation/multi-cluster/kubernetes" + "path": "k8s/deployment-configurations/multi-cluster/kubernetes" }, { "title": "Federation Between VMs and Kubernetes", - "path": "k8s/installation/multi-cluster/vms-and-kubernetes" + "path": "k8s/deployment-configurations/multi-cluster/vms-and-kubernetes" } ] }, @@ -506,65 +474,98 @@ "routes": [ { "title": "Overview", - "path": "k8s/installation/vault" + "path": "k8s/deployment-configurations/vault" }, { "title": "Systems Integration", - "path": "k8s/installation/vault/systems-integration" + "path": "k8s/deployment-configurations/vault/systems-integration" }, { "title": "Data Integration", "routes": [ { "title": "Overview", - "path": "k8s/installation/vault/data-integration" + "path": "k8s/deployment-configurations/vault/data-integration" }, { "title": "Bootstrap Token", - "path": "k8s/installation/vault/data-integration/bootstrap-token" + "path": "k8s/deployment-configurations/vault/data-integration/bootstrap-token" }, { "title": "Enterprise License", - "path": "k8s/installation/vault/data-integration/enterprise-license" + "path": "k8s/deployment-configurations/vault/data-integration/enterprise-license" }, { "title": "Gossip Encryption Key", - "path": "k8s/installation/vault/data-integration/gossip" + "path": "k8s/deployment-configurations/vault/data-integration/gossip" }, { "title": "Partition Token", - "path": "k8s/installation/vault/data-integration/partition-token" + "path": "k8s/deployment-configurations/vault/data-integration/partition-token" }, { "title": "Replication Token", - "path": "k8s/installation/vault/data-integration/replication-token" + "path": "k8s/deployment-configurations/vault/data-integration/replication-token" }, { "title": "Server TLS", - "path": "k8s/installation/vault/data-integration/server-tls" + "path": "k8s/deployment-configurations/vault/data-integration/server-tls" }, { "title": "Service Mesh Certificates", - "path": "k8s/installation/vault/data-integration/connect-ca" + "path": "k8s/deployment-configurations/vault/data-integration/connect-ca" }, { "title": "Snapshot Agent Config", - "path": "k8s/installation/vault/data-integration/snapshot-agent-config" + "path": "k8s/deployment-configurations/vault/data-integration/snapshot-agent-config" }, { "title": "Webhook Certificates", - "path": "k8s/installation/vault/data-integration/webhook-certs" + "path": "k8s/deployment-configurations/vault/data-integration/webhook-certs" } ] }, { "title": "WAN Federation", - "path": "k8s/installation/vault/wan-federation" + "path": "k8s/deployment-configurations/vault/wan-federation" } ] } ] }, + { + "title": "Platform Guides", + "routes": [ + { + "title": "Minikube", + "href": "https://learn.hashicorp.com/tutorials/consul/kubernetes-minikube?utm_source=consul.io&utm_medium=docs&utm_content=k8s&utm_term=mk" + }, + { + "title": "Kind", + "href": "https://learn.hashicorp.com/tutorials/consul/kubernetes-kind?utm_source=consul.io&utm_medium=docs&utm_content=k8s&utm_term=kind" + }, + { + "title": "AKS (Azure)", + "href": "https://learn.hashicorp.com/tutorials/consul/kubernetes-aks-azure?utm_source=consul.io&utm_medium=docs&utm_content=k8s&utm_term=aks" + }, + { + "title": "EKS (AWS)", + "href": "https://learn.hashicorp.com/tutorials/consul/kubernetes-eks-aws?utm_source=consul.io&utm_medium=docs&utm_content=k8s&utm_term=eks" + }, + { + "title": "GKE (Google Cloud)", + "href": "https://learn.hashicorp.com/tutorials/consul/kubernetes-gke-google?utm_source=consul.io&utm_medium=docs&utm_content=k8s&utm_term=gke" + }, + { + "title": "Red Hat OpenShift", + "href": "https://learn.hashicorp.com/tutorials/consul/kubernetes-openshift-red-hat?utm_source=consul.io&utm_medium=docs&utm_content=k8s&utm_term=openshift" + }, + { + "title": "Self Hosted Kubernetes", + "path": "k8s/platforms/self-hosted-kubernetes" + } + ] + }, { "title": "Service Mesh", "routes": [ @@ -693,6 +694,7 @@ } ] }, + { "title": "AWS ECS", "routes": [ diff --git a/website/redirects.js b/website/redirects.js index a4b3f272bb..c9c5b668b0 100644 --- a/website/redirects.js +++ b/website/redirects.js @@ -1278,6 +1278,129 @@ module.exports = [ destination: '/docs/k8s/installation/vault/data-integration/connect-ca', permanent: true, }, + { + source: '/docs/k8s/installation/install#consul-k8s-cli-installation', + destination: '/docs/k8s/installation/install-cli', + permanent: true, + }, + { + source: + '/docs/k8s/installation/deployment-configurations/clients-outside-kubernetes', + destination: + '/docs/k8s/deployment-configurations/clients-outside-kubernetes', + permanent: true, + }, + { + source: + '/docs/k8s/installation/deployment-configurations/servers-outside-kubernetes', + destination: + '/docs/k8s/deployment-configurations/servers-outside-kubernetes', + permanent: true, + }, + { + source: + '/docs/k8s/installation/deployment-configurations/single-dc-multi-k8s', + destination: '/docs/k8s/deployment-configurations/single-dc-multi-k8s', + permanent: true, + }, + { + source: + '/docs/k8s/installation/deployment-configurations/consul-enterprise', + destination: '/docs/k8s/deployment-configurations/consul-enterprise', + permanent: true, + }, + { + source: '/docs/k8s/installation/multi-cluster', + destination: '/docs/k8s/deployment-configurations/multi-cluster', + permanent: true, + }, + { + source: '/docs/k8s/installation/multi-cluster/kubernetes', + destination: '/docs/k8s/deployment-configurations/multi-cluster/kubernetes', + permanent: true, + }, + { + source: '/docs/k8s/installation/multi-cluster/vms-and-kubernetes', + destination: + '/docs/k8s/deployent-configurations/multi-cluster/vms-and-kubernetes', + permanent: true, + }, + { + source: '/docs/k8s/installation/vault', + destination: '/docs/k8s/deployment-configurations/vault', + permanent: true, + }, + { + source: '/docs/k8s/installation/vault/systems-integration', + destination: + '/docs/k8s/deployment-configurations/vault/systems-integration', + permanent: true, + }, + { + source: '/docs/k8s/installation/vault/data-integration', + destination: '/docs/k8s/deployment-configurations/vault/data-integration', + permanent: true, + }, + { + source: '/docs/k8s/installation/vault/data-integration/bootstrap-token', + destination: + '/docs/k8s/deployment-configurations/vault/data-integration/bootstrap-token', + permanent: true, + }, + { + source: '/docs/k8s/installation/vault/data-integration/enterprise-license', + destination: + '/docs/k8s/deployment-configurations/vault/data-integration/enterprise-license', + permanent: true, + }, + { + source: '/docs/k8s/installation/vault/data-integration/gossip', + destination: + '/docs/k8s/deployment-configurations/vault/data-integration/gossip', + permanent: true, + }, + { + source: '/docs/k8s/installation/vault/data-integration/partition-token', + destination: + '/docs/k8s/deployment-configurations/vault/data-integration/partition-token', + permanent: true, + }, + { + source: '/docs/k8s/installation/vault/data-integration/replication-token', + destination: + '/docs/k8s/deployment-configurations/vault/data-integration/replication-token', + permanent: true, + }, + { + source: '/docs/k8s/installation/vault/data-integration/server-tls', + destination: + '/docs/k8s/deployment-configurations/vault/data-integration/server-tls', + permanent: true, + }, + { + source: '/docs/k8s/installation/vault/data-integration/connect-ca', + destination: + '/docs/k8s/deployment-configurations/vault/data-integration/connect-ca', + permanent: true, + }, + { + source: + '/docs/k8s/installation/vault/data-integration/snapshot-agent-config', + destination: + '/docs/k8s/deployment-configurations/vault/data-integration/snapshot-agent-config', + permanent: true, + }, + { + source: '/docs/k8s/installation/vault/data-integration/webhook-certs', + destination: + '/docs/k8s/deployment-configurations/vault/data-integration/webhook-certs', + permanent: true, + }, + { + source: '/docs/k8s/installation/vault/wan-federation', + destination: '/docs/k8s/deployment-configurations/vault/wan-federation', + permanent: true, + }, { source: '/docs/api-gateway/common-errors', destination: '/docs/api-gateway/usage#error-messages', @@ -1288,4 +1411,127 @@ module.exports = [ destination: '/docs/api-gateway/upgrades', permanent: true, }, + { + source: '/docs/k8s/installation/install#consul-k8s-cli-installation', + destination: '/docs/k8s/installation/install-cli', + permanent: true, + }, + { + source: + '/docs/k8s/installation/deployment-configurations/clients-outside-kubernetes', + destination: + '/docs/k8s/deployment-configurations/clients-outside-kubernetes', + permanent: true, + }, + { + source: + '/docs/k8s/installation/deployment-configurations/servers-outside-kubernetes', + destination: + '/docs/k8s/deployment-configurations/servers-outside-kubernetes', + permanent: true, + }, + { + source: + '/docs/k8s/installation/deployment-configurations/single-dc-multi-k8s', + destination: '/docs/k8s/deployment-configurations/single-dc-multi-k8s', + permanent: true, + }, + { + source: + '/docs/k8s/installation/deployment-configurations/consul-enterprise', + destination: '/docs/k8s/deployment-configurations/consul-enterprise', + permanent: true, + }, + { + source: '/docs/k8s/installation/multi-cluster', + destination: '/docs/k8s/deployment-configurations/multi-cluster', + permanent: true, + }, + { + source: '/docs/k8s/installation/multi-cluster/kubernetes', + destination: '/docs/k8s/deployment-configurations/multi-cluster/kubernetes', + permanent: true, + }, + { + source: '/docs/k8s/installation/multi-cluster/vms-and-kubernetes', + destination: + '/docs/k8s/deployent-configurations/multi-cluster/vms-and-kubernetes', + permanent: true, + }, + { + source: '/docs/k8s/installation/vault', + destination: '/docs/k8s/deployment-configurations/vault', + permanent: true, + }, + { + source: '/docs/k8s/installation/vault/systems-integration', + destination: + '/docs/k8s/deployment-configurations/vault/systems-integration', + permanent: true, + }, + { + source: '/docs/k8s/installation/vault/data-integration', + destination: '/docs/k8s/deployment-configurations/vault/data-integration', + permanent: true, + }, + { + source: '/docs/k8s/installation/vault/data-integration/bootstrap-token', + destination: + '/docs/k8s/deployment-configurations/vault/data-integration/bootstrap-token', + permanent: true, + }, + { + source: '/docs/k8s/installation/vault/data-integration/enterprise-license', + destination: + '/docs/k8s/deployment-configurations/vault/data-integration/enterprise-license', + permanent: true, + }, + { + source: '/docs/k8s/installation/vault/data-integration/gossip', + destination: + '/docs/k8s/deployment-configurations/vault/data-integration/gossip', + permanent: true, + }, + { + source: '/docs/k8s/installation/vault/data-integration/partition-token', + destination: + '/docs/k8s/deployment-configurations/vault/data-integration/partition-token', + permanent: true, + }, + { + source: '/docs/k8s/installation/vault/data-integration/replication-token', + destination: + '/docs/k8s/deployment-configurations/vault/data-integration/replication-token', + permanent: true, + }, + { + source: '/docs/k8s/installation/vault/data-integration/server-tls', + destination: + '/docs/k8s/deployment-configurations/vault/data-integration/server-tls', + permanent: true, + }, + { + source: '/docs/k8s/installation/vault/data-integration/connect-ca', + destination: + '/docs/k8s/deployment-configurations/vault/data-integration/connect-ca', + permanent: true, + }, + { + source: + '/docs/k8s/installation/vault/data-integration/snapshot-agent-config', + destination: + '/docs/k8s/deployment-configurations/vault/data-integration/snapshot-agent-config', + permanent: true, + }, + { + source: '/docs/k8s/installation/vault/data-integration/webhook-certs', + destination: + '/docs/k8s/deployment-configurations/vault/data-integration/webhook-certs', + permanent: true, + }, + { + source: '/docs/k8s/installation/vault/wan-federation', + destination: '/docs/k8s/deployment-configurations/vault/wan-federation', + permanent: true, + }, ]