github
/
consul
mirror of https://github.com/hashicorp/consul
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

docs: Multi-port corrections backport (#19229) 

docs: Multi-port corrections (#19224)

* typo fixes and instruction corrections

* typo

* link path correction
pull/19235/head
Jeff Boruszak 2023-10-16 14:17:45 -07:00 committed by GitHub
parent 168a640a90
commit e3088548da
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 26 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
website/content/docs/k8s/multiport/configure.mdx
View File

@ -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:
<CodeBlockConfig name="values.yaml">
@ -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
<Tab heading="Method 1" group="method1">
```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
<Tab heading="Method 2" group="method2">
```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
```
</Tab>
@ -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
```
</Tab>
@ -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
```
</Tab>
@ -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
```
</Tab>

8
website/content/docs/k8s/multiport/index.mdx
View File

@ -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.