From dcd593004ecbdf6dd00f5fe242b7cf998a4d3348 Mon Sep 17 00:00:00 2001 From: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> Date: Mon, 16 Oct 2023 13:52:30 -0700 Subject: [PATCH] docs: Multi-port corrections (#19224) * typo fixes and instruction corrections * typo * link path correction --- .../content/docs/k8s/multiport/configure.mdx | 41 ++++++++++--------- website/content/docs/k8s/multiport/index.mdx | 8 ++-- 2 files changed, 26 insertions(+), 23 deletions(-) diff --git a/website/content/docs/k8s/multiport/configure.mdx b/website/content/docs/k8s/multiport/configure.mdx index 0cae43d471..d53ea521f3 100644 --- a/website/content/docs/k8s/multiport/configure.mdx +++ b/website/content/docs/k8s/multiport/configure.mdx @@ -29,7 +29,7 @@ There are additional requirements for service mesh proxies in transparent proxy ## Enable the v2 catalog -To enable the v2 catalog and its support for multi-port services, set `global.experiments: ["resource-apis"]` and `ui.enabled: false`. The following example includes these parameter in a Helm chart with minimal required configurations for the Consul installation: +To enable the v2 catalog and its support for multi-port services, set `global.experiments: ["resource-apis"]` and `ui.enabled: false`. The following example includes these parameters in a Helm chart with minimal required configurations for the Consul installation: @@ -78,8 +78,8 @@ $ helm install consul hashicorp/consul --create-namespace --namespace consul --v Consul's v2 catalog supports two methods for defining multi-port services in Kubernetes: -- Method 1: Define a single Kubernetes Service that exposes multiple ports -- Method 2: Define multiple Kubernetes Services that expose individual ports +- **Method 1**: Define a single Kubernetes Service that exposes multiple ports +- **Method 2**: Define multiple Kubernetes Services that expose individual ports These methods affect how the Services are addressed in Kubernetes. @@ -338,10 +338,13 @@ spec: To open a shell to the `web` container, you need the name of the Pod it currently runs on. Run the following command to return a list of Pods: ```shell-session -$ kubectl get pods -NAME READY STATUS RESTARTS AGE -api-7dc9d84f-kfnwz 2/2 Running 0 23s -web-7bc5786747-b5pzl 1/1 Running 0 23s +$ kubectl get pods --namespace consul +NAME READY STATUS RESTARTS AGE +api-5784b54bcc-tp98l 3/3 Running 0 6m55s +consul-connect-injector-54865fbcbf-sfjsl 1/1 Running 0 8m33s +consul-server-0 1/1 Running 0 8m33s +consul-webhook-cert-manager-666676bd5b-cdbxc 1/1 Running 0 8m33s +web-6dcbd684bc-gk8n5 2/2 Running 0 6m55s ``` ### Validate both ports @@ -353,14 +356,14 @@ Use the `web` Pod's name to open a shell session and test the `api` service on p ```shell-session -$ kubectl exec -it web-7bc5786747-b5pzl -- curl api:80 +$ kubectl exec -it web-6dcbd684bc-gk8n5 -c web --namespace consul -- curl api:80 hello world ``` Then test the `api` service on port 90. ```shell-session -$ kubectl exec -it web-7bc5786747-b5pzl -- curl api:90 +$ kubectl exec -it web-6dcbd684bc-gk8n5 -c web --namespace consul -- curl api:90 hello world from 9090 admin ``` @@ -369,14 +372,14 @@ hello world from 9090 admin ```shell-session -$ kubectl exec -it web-7bc5786747-b5pzl -- curl api:80 +$ kubectl exec -it web-6dcbd684bc-gk8n5 -c web --namespace consul -- curl api:80 hello world ``` Then test the `api-admin` service on port 90. ```shell-session -$ kubectl exec -it web-7bc5786747-b5pzl -- curl api-admin:90 +$ kubectl exec -it web-6dcbd684bc-gk8n5 -c web --namespace consul -- curl api-admin:90 hello world from 9090 admin ``` @@ -398,14 +401,14 @@ $ kubectl apply -f deny-90.yaml --namespace consul Then, open a shell session in the `web` container and test the `api` service on port 80. ```shell-session -$ kubectl exec -it web-7bc5786747-b5pzl -- curl api:80 +$ kubectl exec -it web-6dcbd684bc-gk8n5 -c web --namespace consul -- curl api:80 hello world ``` Test the `api` service on port 90. This command should fail, indicating that the traffic permission is in effect. ```shell-session -$ kubectl exec -it web-7bc5786747-b5pzl -- curl api:90 +$ kubectl exec -it web-6dcbd684bc-gk8n5 -c web --namespace consul -- curl api:90 ``` @@ -415,14 +418,14 @@ $ kubectl exec -it web-7bc5786747-b5pzl -- curl api:90 Then, open a shell session in the `web` container and test the `api` service on port 80. ```shell-session -$ kubectl exec -it web-7bc5786747-b5pzl -- curl api:80 +$ kubectl exec -it web-6dcbd684bc-gk8n5 -c web --namespace consul -- curl api:80 hello world ``` Test the `admin` service on port 90. This command should fail, indicating that the traffic permission is in effect. ```shell-session -$ kubectl exec -it web-7bc5786747-b5pzl -- curl api-admin:90 +$ kubectl exec -it web-6dcbd684bc-gk8n5 -c web --namespace consul -- curl api-admin:90 ``` @@ -449,14 +452,14 @@ $ kubectl apply -f deny-80.yaml --namespace consul Then, open a shell session in the `web` container and test the `api` service on port 90. ```shell-session -$ kubectl exec -it web-7bc5786747-b5pzl -- curl api:90 +$ kubectl exec -it web-6dcbd684bc-gk8n5 -c web --namespace consul -- curl api:90 hello world from 9090 admin ``` Test the `api` service on port 80. This command should fail, indicating that the traffic permission is in effect. ```shell-session -$ kubectl exec -it web-7bc5786747-b5pzl -- curl api:80 +$ kubectl exec -it web-6dcbd684bc-gk8n5 -c web --namespace consul -- curl api:80 ``` @@ -466,14 +469,14 @@ $ kubectl exec -it web-7bc5786747-b5pzl -- curl api:80 Then, open a shell session in the `web` container and test the `api-admin` service on port 90. ```shell-session -$ kubectl exec -it web-7bc5786747-b5pzl -- curl api-admin:90 +$ kubectl exec -it web-6dcbd684bc-gk8n5 -c web --namespace consul -- curl api-admin:90 hello world from 9090 admin ``` Test the `api` service on port 80. This command should fail, indicating that the traffic permission is in effect. ```shell-session -$ kubectl exec -it web-7bc5786747-b5pzl -- curl api:80 +$ kubectl exec -it web-6dcbd684bc-gk8n5 -c web --namespace consul -- curl api:80 ``` diff --git a/website/content/docs/k8s/multiport/index.mdx b/website/content/docs/k8s/multiport/index.mdx index 9b8ef4dac9..b8ed8e990c 100644 --- a/website/content/docs/k8s/multiport/index.mdx +++ b/website/content/docs/k8s/multiport/index.mdx @@ -14,7 +14,7 @@ Multi-port services are part of a beta release. This documentation supports test This topic describes changes to Consul's catalog that allow you to register a service with multiple ports on Kubernetes deployments. -## Background +## Introduction When Consul registers services, v1 of its catalog API tracks the following information: @@ -22,7 +22,7 @@ When Consul registers services, v1 of its catalog API tracks the following infor - Locations of the _nodes_ the instances run on - Names of the _services_ the instances are associated with -This catalog API was designed prior to the introduction of Consul’s service mesh features. Services and service instances are coupled in the catalog such that Consul's ACL system requires a Kubernetes ServiceAccount resource to match the Service name. As a result, only one service can represent a Kubernetes Workload in the Consul catalog. +This catalog API was designed prior to the introduction of Consul’s service mesh features. The service mesh uses Consul's ACL system, which requires a Kubernetes ServiceAccount resource to match the Service name. As a result, only one service can represent a Kubernetes Workload in the Consul catalog. Since then, the cloud networking needs for applications have evolved and the Consul catalog adapted to support workarounds for these needs. For example, [Kubernetes Pods with multiple ports](/consul/docs/k8s/connect#kubernetes-pods-with-multiple-ports) demonstrates how you can schedule a service with multiple ports so that Consul registers it in the catalog as distinct services with their own service instances. However, this workaround results in additional resource consumption because Consul requires that each service and port use their own proxy and Consul dataplane so that it can recognize them as distinct services. @@ -31,7 +31,7 @@ Since then, the cloud networking needs for applications have evolved and the Con Consul v1.17 introduces a new version of the catalog API designed to bridge differences between the Consul and Kubernetes data models. The v2 catalog API still tracks services and nodes for Consul, but replaces service instances with _workloads_ and _workload identites_. - `Workload` is an application instance running in a set of one or more Pods scheduled according to a Kubernetes Workload resource such as a Deployment or StatefulSet. It is similar to [Kubernetes Workloads](https://kubernetes.io/docs/concepts/workloads/). -- `WorkloadIdentities` provide a distinct identity for a Workload to assume in a Kubernetes cluster. THey are similar to [Kubernetes Service Accounts](https://kubernetes.io/docs/concepts/security/service-accounts/). +- `WorkloadIdentities` provide a distinct identity for a Workload to assume in a Kubernetes cluster. They are similar to [Kubernetes Service Accounts](https://kubernetes.io/docs/concepts/security/service-accounts/). This catalog structure enables Consul to associate a single Kubernetes Workload with multiple services in its catalog. @@ -61,7 +61,7 @@ For an example configuration and instructions for each of the steps in this work Be aware of the following constraints and technical limitations on using multi-port services and the v2 catalog API: -- The v2 catalog API beta does not support connections with client agents. It is only available for Kubernetes deployments, which use [Consul dataplanes](consul/docs/connect/dataplane) instead of client agents. +- The v2 catalog API beta does not support connections with client agents. It is only available for Kubernetes deployments, which use [Consul dataplanes](/consul/docs/connect/dataplane) instead of client agents. - The v1 and v2 catalog APIs cannot run concurrently. - The Consul UI does not support multi-port services or the v2 catalog API in this release. You must disable the UI in the Helm chart in order to use the v2 catalog API. - HCP Consul does not support multi-port services or the v2 catalog API in this release.