From abfa3493959b63f460ddc676fe7cbb6e0cefc1d2 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Wed, 16 Feb 2022 11:54:43 -0800 Subject: [PATCH 01/40] added 'Tech Specs' section under API Gateway --- .../docs/api-gateway/api-gateway-tech-specs.mdx | 8 ++++++++ .../docs/{ => api-gateway}/api-gateway.mdx | 3 ++- website/data/docs-nav-data.json | 15 ++++++++++++--- 3 files changed, 22 insertions(+), 4 deletions(-) create mode 100644 website/content/docs/api-gateway/api-gateway-tech-specs.mdx rename website/content/docs/{ => api-gateway}/api-gateway.mdx (99%) diff --git a/website/content/docs/api-gateway/api-gateway-tech-specs.mdx b/website/content/docs/api-gateway/api-gateway-tech-specs.mdx new file mode 100644 index 0000000000..a57e5cfb43 --- /dev/null +++ b/website/content/docs/api-gateway/api-gateway-tech-specs.mdx @@ -0,0 +1,8 @@ +--- +layout: docs +page_title: Consul API Gateway Technical Specifications +description: >- + This topic describes technical specifications for Consul API Gateway. +--- + +# Technical Specifications \ No newline at end of file diff --git a/website/content/docs/api-gateway.mdx b/website/content/docs/api-gateway/api-gateway.mdx similarity index 99% rename from website/content/docs/api-gateway.mdx rename to website/content/docs/api-gateway/api-gateway.mdx index 7c1c096b92..62a0a0f59f 100644 --- a/website/content/docs/api-gateway.mdx +++ b/website/content/docs/api-gateway/api-gateway.mdx @@ -1,7 +1,8 @@ --- layout: docs page_title: API Gateway -description: Using Consul API gateway functionality +description: >- + Using Consul API gateway functionality --- # Consul API Gateway diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 5138a99878..5bee60376d 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -373,10 +373,19 @@ "hidden": true } ] - }, + }, { - "title": "Consul API Gateway BETA", - "path": "api-gateway" + "title": "Consul API Gateway", + "routes": [ + { + "title": "Consul API Gateway", + "path": "api-gateway/api-gateway" + }, + { + "title": "Technical Specifications", + "path": "api-gateway/api-gateway-tech-specs" + } + ] }, { "title": "Kubernetes", From 305c78ccbced4b5c4a923098f6ed5b428e02e735 Mon Sep 17 00:00:00 2001 From: Mike Morris Date: Tue, 22 Feb 2022 11:23:22 -0500 Subject: [PATCH 02/40] website: remove -beta prerelease tag from api-gateway CRD and image refs --- website/content/docs/api-gateway/api-gateway.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/website/content/docs/api-gateway/api-gateway.mdx b/website/content/docs/api-gateway/api-gateway.mdx index 62a0a0f59f..f552a9bab4 100644 --- a/website/content/docs/api-gateway/api-gateway.mdx +++ b/website/content/docs/api-gateway/api-gateway.mdx @@ -22,7 +22,7 @@ Consul API Gateway implements the Kubernetes [Gateway API Specification](https:/ Your datacenter must meet the following requirements prior to configuring the Consul API Gateway: -- Kubernetes 1.21+ +- Kubernetes 1.21+ - `kubectl` 1.21+ - Consul 1.11.2+ - HashiCorp Consul Helm chart 0.40.0+ @@ -34,12 +34,12 @@ Your datacenter must meet the following requirements prior to configuring the Co ```shell-session - $ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?ref=v0.1.0-beta" + $ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?ref=v0.1.0" ``` -1. Create a `values.yaml` file for your Consul API Gateway deployment. Copy the content below into the `values.yaml` file. The `values.yaml` will be used by the Consul Helm chart. See [Helm Chart Configuration - apigateway](https://www.consul.io/docs/k8s/helm#apigateway) for more available options on how to configure your Consul API Gateway deployment via the Helm chart. +1. Create a `values.yaml` file for your Consul API Gateway deployment. Copy the content below into the `values.yaml` file. The `values.yaml` will be used by the Consul Helm chart. See [Helm Chart Configuration - apigateway](https://www.consul.io/docs/k8s/helm#apigateway) for more available options on how to configure your Consul API Gateway deployment via the Helm chart. @@ -55,7 +55,7 @@ Your datacenter must meet the following requirements prior to configuring the Co enabled: true apiGateway: enabled: true - image: hashicorp/consul-api-gateway:0.1.0-beta + image: hashicorp/consul-api-gateway:0.1.0 ``` From 0cb01f6a47c7a7edb00bf146ff8c7c755f14cb87 Mon Sep 17 00:00:00 2001 From: Mike Morris Date: Tue, 22 Feb 2022 12:31:09 -0500 Subject: [PATCH 03/40] website: bump Consul Helm chart req for Consul API Gateway to 0.41.0 --- website/content/docs/api-gateway/api-gateway.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/content/docs/api-gateway/api-gateway.mdx b/website/content/docs/api-gateway/api-gateway.mdx index f552a9bab4..3fe7a46922 100644 --- a/website/content/docs/api-gateway/api-gateway.mdx +++ b/website/content/docs/api-gateway/api-gateway.mdx @@ -25,7 +25,7 @@ Your datacenter must meet the following requirements prior to configuring the Co - Kubernetes 1.21+ - `kubectl` 1.21+ - Consul 1.11.2+ -- HashiCorp Consul Helm chart 0.40.0+ +- HashiCorp Consul Helm chart 0.41.0+ ## Installation @@ -65,7 +65,7 @@ Your datacenter must meet the following requirements prior to configuring the Co ```shell-session - $ helm install consul hashicorp/consul --version 0.40.0 --values values.yaml + $ helm install consul hashicorp/consul --version 0.41.0 --values values.yaml ``` From 6356da1855d4663de36ffe977654d607cbb18d52 Mon Sep 17 00:00:00 2001 From: Mike Morris Date: Tue, 22 Feb 2022 13:07:21 -0500 Subject: [PATCH 04/40] website: adds docs for Consul Helm chart apiGateway > consulNamespaces --- website/content/docs/k8s/helm.mdx | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/website/content/docs/k8s/helm.mdx b/website/content/docs/k8s/helm.mdx index 6d9f600d5a..b37010b973 100644 --- a/website/content/docs/k8s/helm.mdx +++ b/website/content/docs/k8s/helm.mdx @@ -2024,6 +2024,13 @@ Use these links to navigate to a particular top-level stanza. annotations: | "annotation-key": "annotation-value" ``` + - `consulNamespaces` ((#v-apigateway-consulnamespaces)) - These settings manage the Consul API Gateway's interaction with Consul namespaces. Requires `global.enableConsulNamespaces` to be set to `true` and Consul Enterprise v1.7+ with a valid Consul Enterprise license. + + - `consulDestinationNamespace` ((#v-apigateway-consulnamespaces-consuldestinationnamespace)) (`string: "default"`) - Name of the Consul namespace to register all k8s services into. If the Consul namespace does not already exist, it will be created. This will be ignored if `mirroringK8S` is set to `true`. + + - `mirroringK8S` ((#v-apigateway-consulnamespaces-mirroringk8s)) (`boolean: false`) - If true, k8s services will be registered into a Consul namespace of the same name as their k8s namespace, optionally prefixed if `mirroringK8SPrefix` is set below. If the Consul namespace does not already exist, it will be created. Turning this on overrides the `consulDestinationNamespace` setting. `addK8SNamespaceSuffix` may no longer be needed if enabling this option. + + - `mirroringK8SPrefix` ((#v-apigateway-consulnamespaces-mirroringk8sprefix)) (`string: ""`) - If `mirroringK8S` is set to `true`, `mirroringK8SPrefix` allows each Consul namespace to be given a prefix. For example, if `mirroringK8SPrefix` is set to "k8s-", a service in the k8s `staging` namespace will be registered into the `k8s-staging` Consul namespace. ### webhookCertManager From 5b80764fc01279cdfba0ee7094553c7c25260b53 Mon Sep 17 00:00:00 2001 From: Mike Morris Date: Tue, 22 Feb 2022 13:31:17 -0500 Subject: [PATCH 05/40] website: clarify install step for Consul API Gateway CRDs --- website/content/docs/api-gateway/api-gateway.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/api-gateway.mdx b/website/content/docs/api-gateway/api-gateway.mdx index 3fe7a46922..07c2562790 100644 --- a/website/content/docs/api-gateway/api-gateway.mdx +++ b/website/content/docs/api-gateway/api-gateway.mdx @@ -29,7 +29,7 @@ Your datacenter must meet the following requirements prior to configuring the Co ## Installation -1. Issue the following command to install the Consul API Gateway controller: +1. Issue the following command to install the CRDs: From ea5816505da22dd430d8bc492b9bfb71a127bafc Mon Sep 17 00:00:00 2001 From: Mike Morris Date: Tue, 22 Feb 2022 13:42:25 -0500 Subject: [PATCH 06/40] Revert "website: adds docs for Consul Helm chart apiGateway > consulNamespaces" This reverts commit 6356da1855d4663de36ffe977654d607cbb18d52. I didn't notice the DO NOT EDIT note that this file is generated automatically. --- website/content/docs/k8s/helm.mdx | 7 ------- 1 file changed, 7 deletions(-) diff --git a/website/content/docs/k8s/helm.mdx b/website/content/docs/k8s/helm.mdx index b37010b973..6d9f600d5a 100644 --- a/website/content/docs/k8s/helm.mdx +++ b/website/content/docs/k8s/helm.mdx @@ -2024,13 +2024,6 @@ Use these links to navigate to a particular top-level stanza. annotations: | "annotation-key": "annotation-value" ``` - - `consulNamespaces` ((#v-apigateway-consulnamespaces)) - These settings manage the Consul API Gateway's interaction with Consul namespaces. Requires `global.enableConsulNamespaces` to be set to `true` and Consul Enterprise v1.7+ with a valid Consul Enterprise license. - - - `consulDestinationNamespace` ((#v-apigateway-consulnamespaces-consuldestinationnamespace)) (`string: "default"`) - Name of the Consul namespace to register all k8s services into. If the Consul namespace does not already exist, it will be created. This will be ignored if `mirroringK8S` is set to `true`. - - - `mirroringK8S` ((#v-apigateway-consulnamespaces-mirroringk8s)) (`boolean: false`) - If true, k8s services will be registered into a Consul namespace of the same name as their k8s namespace, optionally prefixed if `mirroringK8SPrefix` is set below. If the Consul namespace does not already exist, it will be created. Turning this on overrides the `consulDestinationNamespace` setting. `addK8SNamespaceSuffix` may no longer be needed if enabling this option. - - - `mirroringK8SPrefix` ((#v-apigateway-consulnamespaces-mirroringk8sprefix)) (`string: ""`) - If `mirroringK8S` is set to `true`, `mirroringK8SPrefix` allows each Consul namespace to be given a prefix. For example, if `mirroringK8SPrefix` is set to "k8s-", a service in the k8s `staging` namespace will be registered into the `k8s-staging` Consul namespace. ### webhookCertManager From d9af637bf79404ddf9dfda64551f3a7abb6ffec2 Mon Sep 17 00:00:00 2001 From: Mike Morris Date: Tue, 22 Feb 2022 13:44:53 -0500 Subject: [PATCH 07/40] website: removed tls: enabled from minimal Consul API Gateway Helm config --- website/content/docs/api-gateway/api-gateway.mdx | 2 -- 1 file changed, 2 deletions(-) diff --git a/website/content/docs/api-gateway/api-gateway.mdx b/website/content/docs/api-gateway/api-gateway.mdx index 07c2562790..4482d352d3 100644 --- a/website/content/docs/api-gateway/api-gateway.mdx +++ b/website/content/docs/api-gateway/api-gateway.mdx @@ -47,8 +47,6 @@ Your datacenter must meet the following requirements prior to configuring the Co global: name: consul image: 'hashicorp/consul:1.11.2' - tls: - enabled: true connectInject: enabled: true controller: From 5d06b304673cf3ff808e3a950980350be7422d5a Mon Sep 17 00:00:00 2001 From: Mike Morris Date: Tue, 22 Feb 2022 15:12:32 -0500 Subject: [PATCH 08/40] website: reorder GatewayClass below GatewayClassConfig --- .../content/docs/api-gateway/api-gateway.mdx | 60 +++++++++---------- 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/website/content/docs/api-gateway/api-gateway.mdx b/website/content/docs/api-gateway/api-gateway.mdx index 4482d352d3..c3ef0cc8f2 100644 --- a/website/content/docs/api-gateway/api-gateway.mdx +++ b/website/content/docs/api-gateway/api-gateway.mdx @@ -141,36 +141,6 @@ Configure the following artifacts to facilitate ingress into your Consul service - [Gateway](#gateway): Defines the main infrastructure resource that links API gateway components. It specifies the name of the `GatewayClass` and one or more `listeners` (see [Listeners](#listeners)), which specify the logical endpoints bound to the gateway's addresses. - [Routes](#routes): Specifies the path from the client to the listener. -### GatewayClass - -The `GatewayClass` resource is used as a template for creating `Gateway` resources. -The specification includes the name of the controller (`controllerName`) and an API object containing controller-specific configuration resources within the cluster (`parametersRef`). -The value of the `controllerName` field must be set to `hashicorp.com/consul-api-gateway-controller`. - -When gateways are created from a `GatewayClass`, they use the parameters specified in the `GatewayClass` at the time of instantiation. - -Add the `kind: GatewayClass` option to the the gateway values file to declare a gateway class. -The following example creates a gateway class called `test-gateway-class`: - - - -```yaml -apiVersion: gateway.networking.k8s.io/v1alpha2 -kind: GatewayClass -metadata: - name: test-gateway-class -spec: - controllerName: 'hashicorp.com/consul-api-gateway-controller' - parametersRef: - group: api-gateway.consul.hashicorp.com - kind: GatewayClassConfig - name: test-gateway-class-config -``` - - - -Refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.GatewayClass) for details about configuring gateway classes. - ### GatewayClassConfig The `GatewayClassConfig` object describes additional Consul API Gateway-related configuration parameters for the `GatewayClass`. @@ -220,6 +190,36 @@ The following table describes the required parameters for the `spec` array: Refer to the [Consul API Gateway repository](https://github.com/hashicorp/consul-api-gateway/blob/main/config/crd/bases/api-gateway.consul.hashicorp.com_gatewayclassconfigs.yaml) for the complete specification. +### GatewayClass + +The `GatewayClass` resource is used as a template for creating `Gateway` resources. +The specification includes the name of the controller (`controllerName`) and an API object containing controller-specific configuration resources within the cluster (`parametersRef`). +The value of the `controllerName` field must be set to `hashicorp.com/consul-api-gateway-controller`. + +When gateways are created from a `GatewayClass`, they use the parameters specified in the `GatewayClass` at the time of instantiation. + +Add the `kind: GatewayClass` option to the the gateway values file to declare a gateway class. +The following example creates a gateway class called `test-gateway-class`: + + + +```yaml +apiVersion: gateway.networking.k8s.io/v1alpha2 +kind: GatewayClass +metadata: + name: test-gateway-class +spec: + controllerName: 'hashicorp.com/consul-api-gateway-controller' + parametersRef: + group: api-gateway.consul.hashicorp.com + kind: GatewayClassConfig + name: test-gateway-class-config +``` + + + +Refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.GatewayClass) for details about configuring gateway classes. + ### Gateway The gateway configuration is the main infrastructure resource that links API gateway components. It specifies the name of the `GatewayClass` and one or more `listeners`. From 721d796e02164bd068b1b577265732a4062b7fec Mon Sep 17 00:00:00 2001 From: Mike Morris Date: Tue, 22 Feb 2022 15:17:05 -0500 Subject: [PATCH 09/40] website: minor fixups on Consul API Gateway GatewayClassConfig --- website/content/docs/api-gateway/api-gateway.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/website/content/docs/api-gateway/api-gateway.mdx b/website/content/docs/api-gateway/api-gateway.mdx index c3ef0cc8f2..d977152048 100644 --- a/website/content/docs/api-gateway/api-gateway.mdx +++ b/website/content/docs/api-gateway/api-gateway.mdx @@ -143,10 +143,10 @@ Configure the following artifacts to facilitate ingress into your Consul service ### GatewayClassConfig -The `GatewayClassConfig` object describes additional Consul API Gateway-related configuration parameters for the `GatewayClass`. +The `GatewayClassConfig` object describes Consul API Gateway-related configuration parameters for the [`GatewayClass`](#gatewayclass). Add the `kind: GatewayClassConfig` option to the gateway values file to declare a gateway class. -The following example creates a gateway class called `test-gateway-class-config`: +The following example creates a gateway class config called `test-gateway-class-config`: @@ -168,7 +168,7 @@ spec: -The following table describes the required parameters for the `spec` array: +The following table describes the allowed parameters for the `spec` array: | Parameter | Description | Type | Default | | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------ | From 54dcdcee9ac8fcf62f1a752b1fec0d3e23cd62c7 Mon Sep 17 00:00:00 2001 From: Mike Morris Date: Tue, 22 Feb 2022 15:32:32 -0500 Subject: [PATCH 10/40] website: remove nonexistant fatal log level from Gateway API docs --- website/content/docs/api-gateway/api-gateway.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/api-gateway.mdx b/website/content/docs/api-gateway/api-gateway.mdx index d977152048..a28d410e49 100644 --- a/website/content/docs/api-gateway/api-gateway.mdx +++ b/website/content/docs/api-gateway/api-gateway.mdx @@ -183,7 +183,7 @@ The following table describes the allowed parameters for the `spec` array: | `copyAnnotations.service` | List of annotations to copy to the gateway service. | Array | `["external-dns.alpha.kubernetes.io/hostname"]` | | `image.consulAPIGateway` | The image to use for consul-api-gateway. | String | `"hashicorp/consul-api-gateway:RELEASE_VERSION"` | | `image.envoy` | Specifies the container image to use for Envoy. | String | `"envoyproxy/envoy:v1.19-latest"` | -| `logLevel` | Specifies the error reporting level for logs. You can specify the following values: `fatal`, `error`, `warning`, `info`, `debug`, `trace`. | String | `"info"` | +| `logLevel` | Specifies the error reporting level for logs. You can specify the following values: `error`, `warning`, `info`, `debug`, `trace`. | String | `"info"` | | `nodeSelector` | Specifies a set of parameters that constrain the nodes on which the pod can run. Defining nodes with the `nodeSelector` enables the pod to fit on a node. The selector must match a node's labels for the pod to be scheduled on that node. Refer to the [Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/) for additional information. | Object | N/A | | `serviceType` | Specifies the ingress methods for a service. The following values are supported:
`ClusterIP`
`NodePort`
`LoadBalancer`. | String | N/A | | `useHostPorts` | If set to `true`, then the Envoy container ports are mapped to host ports. | Boolean | `false` | From 9e3e3c28ec2ab29c6f73dbbbe4b53f16fd410bf4 Mon Sep 17 00:00:00 2001 From: Mike Morris Date: Tue, 22 Feb 2022 15:58:06 -0500 Subject: [PATCH 11/40] website: clarify usage section for API Gateway --- .../content/docs/api-gateway/api-gateway.mdx | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/website/content/docs/api-gateway/api-gateway.mdx b/website/content/docs/api-gateway/api-gateway.mdx index a28d410e49..126defe0c1 100644 --- a/website/content/docs/api-gateway/api-gateway.mdx +++ b/website/content/docs/api-gateway/api-gateway.mdx @@ -71,14 +71,25 @@ Your datacenter must meet the following requirements prior to configuring the Co ## Usage 1. Verify that the [requirements](#requirements) have been met. -1. Verify that the Consul API Gateway software has been installed and applied (see [Installation](#installation)). -1. Configure the artifacts described in [Configuration](#configuration). +1. Verify that the Consul API Gateway CRDs and controller have been installed and applied (see [Installation](#installation)). +1. Configure the artifacts described below in [Configuration](#configuration). If the following config is added to the `values.yaml` Helm config, the GatewayClassConfig and GatewayClass will be created automatically, and only the Gateway, Listeners and Routes will need to be configured manually. The `serviceType` for a managed GatewayClass will default to `LoadBalancer`, which is appropriate for most deployments to managed Kubernetes cloud offerings (EKS, GKE, AKS) - other deployments, such as to a [kind](https://kind.sigs.k8s.io/) cluster, may require specifying `NodePort` or `ClusterIP` instead. + + + + ```yaml + apiGateway: + managedGatewayClass: + enabled: true + ``` + + + 1. Issue the `kubectl apply` command to implement the configurations, e.g.: ```shell-session - $ kubectl apply --values gateway-configuration.yaml + $ kubectl apply -f gateway.yaml routes.yaml ``` From 03be4106c2fcf16ee23ab39664342b5ed3ff424c Mon Sep 17 00:00:00 2001 From: Mike Morris Date: Tue, 22 Feb 2022 16:05:39 -0500 Subject: [PATCH 12/40] website: add MeshService custom resource documentation --- website/content/docs/api-gateway/api-gateway.mdx | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/website/content/docs/api-gateway/api-gateway.mdx b/website/content/docs/api-gateway/api-gateway.mdx index 126defe0c1..a780b19717 100644 --- a/website/content/docs/api-gateway/api-gateway.mdx +++ b/website/content/docs/api-gateway/api-gateway.mdx @@ -317,3 +317,14 @@ spec: ``` + + +### MeshService + +MeshService holds a reference to an externally managed Consul Service Mesh service, and can be used as a `backendRef` for a [`Route`](#route). + +| Parameter | Description | Type | Default | +| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------- | +| `name` | Specifies the service name for a Consul service. It is assumed this service will exist in either the `consulDestinationNamespace` or mirrored Consul namespace from where this custom resource is defined, depending on the Helm configuration. + +Refer to the [Consul API Gateway repository](https://github.com/hashicorp/consul-api-gateway/blob/main/config/crd/bases/api-gateway.consul.hashicorp.com_meshservices.yaml) for the complete specification. From 7aea8e8fc8547dd8cbc1b580c287494f85d3f857 Mon Sep 17 00:00:00 2001 From: Mike Morris Date: Tue, 22 Feb 2022 16:12:05 -0500 Subject: [PATCH 13/40] website: remove invalid caSecret config from GatewayGlassConfig example --- website/content/docs/api-gateway/api-gateway.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/website/content/docs/api-gateway/api-gateway.mdx b/website/content/docs/api-gateway/api-gateway.mdx index a780b19717..a7dea1b499 100644 --- a/website/content/docs/api-gateway/api-gateway.mdx +++ b/website/content/docs/api-gateway/api-gateway.mdx @@ -171,7 +171,6 @@ spec: logLevel: 'trace' consul: scheme: 'https' - caSecret: 'consul-ca-cert' ports: http: 8501 grpc: 8502 From ecf9540f8e32200452ab92df796e0a1874e88fd8 Mon Sep 17 00:00:00 2001 From: Mike Morris Date: Tue, 22 Feb 2022 16:22:48 -0500 Subject: [PATCH 14/40] website: remove ref to a specific version of envoyproxy/envoy from API Gateway docs --- website/content/docs/api-gateway/api-gateway.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/api-gateway.mdx b/website/content/docs/api-gateway/api-gateway.mdx index a7dea1b499..616f18097c 100644 --- a/website/content/docs/api-gateway/api-gateway.mdx +++ b/website/content/docs/api-gateway/api-gateway.mdx @@ -192,7 +192,7 @@ The following table describes the allowed parameters for the `spec` array: | `consul.scheme` | Specifies the scheme to use for connecting to Consul. The supported values are `"http"` and `"https"`. | String | `"http"` | | `copyAnnotations.service` | List of annotations to copy to the gateway service. | Array | `["external-dns.alpha.kubernetes.io/hostname"]` | | `image.consulAPIGateway` | The image to use for consul-api-gateway. | String | `"hashicorp/consul-api-gateway:RELEASE_VERSION"` | -| `image.envoy` | Specifies the container image to use for Envoy. | String | `"envoyproxy/envoy:v1.19-latest"` | +| `image.envoy` | Specifies the container image to use for Envoy. View available image tags on [DockerHub](https://hub.docker.com/r/envoyproxy/envoy/tags). | String | `"envoyproxy/envoy:RELEASE_VERSION"` | | `logLevel` | Specifies the error reporting level for logs. You can specify the following values: `error`, `warning`, `info`, `debug`, `trace`. | String | `"info"` | | `nodeSelector` | Specifies a set of parameters that constrain the nodes on which the pod can run. Defining nodes with the `nodeSelector` enables the pod to fit on a node. The selector must match a node's labels for the pod to be scheduled on that node. Refer to the [Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/) for additional information. | Object | N/A | | `serviceType` | Specifies the ingress methods for a service. The following values are supported:
`ClusterIP`
`NodePort`
`LoadBalancer`. | String | N/A | From 48489b80e6883b298d808d3ea539dbcbc73e674a Mon Sep 17 00:00:00 2001 From: Mike Morris Date: Tue, 22 Feb 2022 16:25:13 -0500 Subject: [PATCH 15/40] website: add DockerHub link for consulAPIGateway image config --- website/content/docs/api-gateway/api-gateway.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/api-gateway.mdx b/website/content/docs/api-gateway/api-gateway.mdx index 616f18097c..7ab4b97494 100644 --- a/website/content/docs/api-gateway/api-gateway.mdx +++ b/website/content/docs/api-gateway/api-gateway.mdx @@ -191,7 +191,7 @@ The following table describes the allowed parameters for the `spec` array: | `consul.ports.http` | Specifies the port for Consul's HTTP server. | Integer | `8500` | | `consul.scheme` | Specifies the scheme to use for connecting to Consul. The supported values are `"http"` and `"https"`. | String | `"http"` | | `copyAnnotations.service` | List of annotations to copy to the gateway service. | Array | `["external-dns.alpha.kubernetes.io/hostname"]` | -| `image.consulAPIGateway` | The image to use for consul-api-gateway. | String | `"hashicorp/consul-api-gateway:RELEASE_VERSION"` | +| `image.consulAPIGateway` | The image to use for consul-api-gateway. View available image tags on [DockerHub](https://hub.docker.com/r/hashicorp/consul-api-gateway/tags). | String | `"hashicorp/consul-api-gateway:RELEASE_VERSION"` | | `image.envoy` | Specifies the container image to use for Envoy. View available image tags on [DockerHub](https://hub.docker.com/r/envoyproxy/envoy/tags). | String | `"envoyproxy/envoy:RELEASE_VERSION"` | | `logLevel` | Specifies the error reporting level for logs. You can specify the following values: `error`, `warning`, `info`, `debug`, `trace`. | String | `"info"` | | `nodeSelector` | Specifies a set of parameters that constrain the nodes on which the pod can run. Defining nodes with the `nodeSelector` enables the pod to fit on a node. The selector must match a node's labels for the pod to be scheduled on that node. Refer to the [Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/) for additional information. | Object | N/A | From 5c7b3e3b8c93afcb25b1b97da25665a1d91913b1 Mon Sep 17 00:00:00 2001 From: Mike Morris Date: Tue, 22 Feb 2022 16:29:38 -0500 Subject: [PATCH 16/40] website: add link for serviceType Helm chart config for apiGateway --- website/content/docs/api-gateway/api-gateway.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/api-gateway.mdx b/website/content/docs/api-gateway/api-gateway.mdx index 7ab4b97494..5edad13fd2 100644 --- a/website/content/docs/api-gateway/api-gateway.mdx +++ b/website/content/docs/api-gateway/api-gateway.mdx @@ -72,7 +72,7 @@ Your datacenter must meet the following requirements prior to configuring the Co 1. Verify that the [requirements](#requirements) have been met. 1. Verify that the Consul API Gateway CRDs and controller have been installed and applied (see [Installation](#installation)). -1. Configure the artifacts described below in [Configuration](#configuration). If the following config is added to the `values.yaml` Helm config, the GatewayClassConfig and GatewayClass will be created automatically, and only the Gateway, Listeners and Routes will need to be configured manually. The `serviceType` for a managed GatewayClass will default to `LoadBalancer`, which is appropriate for most deployments to managed Kubernetes cloud offerings (EKS, GKE, AKS) - other deployments, such as to a [kind](https://kind.sigs.k8s.io/) cluster, may require specifying `NodePort` or `ClusterIP` instead. +1. Configure the artifacts described below in [Configuration](#configuration). If the following config is added to the `values.yaml` Helm config, the GatewayClassConfig and GatewayClass will be created automatically, and only the Gateway, Listeners and Routes will need to be configured manually. The [`serviceType`](https://www.consul.io/docs/k8s/helm#v-apigateway-managedgatewayclass-servicetype) for a managed GatewayClass will default to `LoadBalancer`, which is appropriate for most deployments to managed Kubernetes cloud offerings (EKS, GKE, AKS) - other deployments, such as to a [kind](https://kind.sigs.k8s.io/) cluster, may require specifying `NodePort` or `ClusterIP` instead. From c5342cfe5ff2e16be9468a193349cf9a9421730a Mon Sep 17 00:00:00 2001 From: Nathan Coleman Date: Tue, 22 Feb 2022 16:57:04 -0500 Subject: [PATCH 17/40] Add technical specifications --- .../api-gateway/api-gateway-tech-specs.mdx | 59 ++++++++++++++++++- 1 file changed, 58 insertions(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/api-gateway-tech-specs.mdx b/website/content/docs/api-gateway/api-gateway-tech-specs.mdx index a57e5cfb43..c63abd3eed 100644 --- a/website/content/docs/api-gateway/api-gateway-tech-specs.mdx +++ b/website/content/docs/api-gateway/api-gateway-tech-specs.mdx @@ -5,4 +5,61 @@ description: >- This topic describes technical specifications for Consul API Gateway. --- -# Technical Specifications \ No newline at end of file +# Technical Specifications + +## Required Software and Supported Versions + +## Consul Server Deployments + +- Consul Editions supported: OSS and Enterprise +- Supported Consul Server deployment types: + - Self Managed + - HCP Consul + +## Deployment Environments + +Consul API Gateway can be deployed in the following Kubernetes-based environments: + +- Generic Kubernetes +- AWS Elastic Kubernetes Service (EKS) +- Google Kubernetes Engine (GKE) +- Azure Kubernetes Service (AKS) + +## Kubernetes Gateway API Specification + +Supported version of the Gateway API spec: v1alpha2 + + +## Resource Allocations + +### Gateway Controller Pod + +| Resource | Allocation | +| -------- | -------------------------------------------------------------------------------------------------------- | +| CPU | None specified. Will use namespace or cluster default depending on the Kubernetes cluster configuration. | +| Memory | None specified. Will use namespace or cluster default depending on the Kubernetes cluster configuration. | + +### Gateway Instance Pod + +| Resource | Allocation | +| -------- | -------------------------------------------------------------------------------------------------------- | +| CPU | None specified. Will use namespace or cluster default depending on the Kubernetes cluster configuration. | +| Memory | None specified. Will use namespace or cluster default depending on the Kubernetes cluster configuration. | + +## TCP Ports Required + +The tables below lists the TCP ports that are used by each component of the API Gateway. + +### Gateway Controller Pod + +| Port | Used For | +| ---- | ------------------------------------------------------------------ | +| 9090 | Secret Discovery Service (SDS) | +| Configurable | Port for scraping Prometheus metrics. Disabled by default. | + +### Gateway Instance Pod + +| Port | Used For | +| ----- | ----------------------------- | +| 9090 | Secret Discovery Service (SDS) | +| 20000 | Kubernetes readiness probe | From 62a8b295c475ac8f7b22e1331da4039d718333c9 Mon Sep 17 00:00:00 2001 From: Nathan Coleman Date: Tue, 22 Feb 2022 17:27:28 -0500 Subject: [PATCH 18/40] Add descriptor for resource allocation tables Also fix typo under TCP Ports Required --- website/content/docs/api-gateway/api-gateway-tech-specs.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/api-gateway-tech-specs.mdx b/website/content/docs/api-gateway/api-gateway-tech-specs.mdx index c63abd3eed..0cd0f5ff45 100644 --- a/website/content/docs/api-gateway/api-gateway-tech-specs.mdx +++ b/website/content/docs/api-gateway/api-gateway-tech-specs.mdx @@ -32,6 +32,8 @@ Supported version of the Gateway API spec: v1alpha2 ## Resource Allocations +The tables below list the resource allocations for each component of the API Gateway. + ### Gateway Controller Pod | Resource | Allocation | @@ -48,7 +50,7 @@ Supported version of the Gateway API spec: v1alpha2 ## TCP Ports Required -The tables below lists the TCP ports that are used by each component of the API Gateway. +The tables below list the TCP ports that are used by each component of the API Gateway. ### Gateway Controller Pod From 03cffa25cf2e5afbd19fae5b5969103f16dcaf35 Mon Sep 17 00:00:00 2001 From: Nathan Coleman Date: Tue, 22 Feb 2022 17:43:46 -0500 Subject: [PATCH 19/40] Move software requirements to Technical Specifications page --- .../content/docs/api-gateway/api-gateway-tech-specs.mdx | 9 ++++++++- website/content/docs/api-gateway/api-gateway.mdx | 7 +------ 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/website/content/docs/api-gateway/api-gateway-tech-specs.mdx b/website/content/docs/api-gateway/api-gateway-tech-specs.mdx index 0cd0f5ff45..12245b1848 100644 --- a/website/content/docs/api-gateway/api-gateway-tech-specs.mdx +++ b/website/content/docs/api-gateway/api-gateway-tech-specs.mdx @@ -9,11 +9,18 @@ description: >- ## Required Software and Supported Versions +Your datacenter must meet the following requirements prior to configuring the Consul API Gateway: + +- Kubernetes 1.21+ +- `kubectl` 1.21+ +- Consul 1.11.2+ +- HashiCorp Consul Helm chart 0.41.0+ + ## Consul Server Deployments - Consul Editions supported: OSS and Enterprise - Supported Consul Server deployment types: - - Self Managed + - Self-Managed - HCP Consul ## Deployment Environments diff --git a/website/content/docs/api-gateway/api-gateway.mdx b/website/content/docs/api-gateway/api-gateway.mdx index 5edad13fd2..3c84c8b597 100644 --- a/website/content/docs/api-gateway/api-gateway.mdx +++ b/website/content/docs/api-gateway/api-gateway.mdx @@ -20,12 +20,7 @@ Consul API Gateway implements the Kubernetes [Gateway API Specification](https:/ ## Requirements -Your datacenter must meet the following requirements prior to configuring the Consul API Gateway: - -- Kubernetes 1.21+ -- `kubectl` 1.21+ -- Consul 1.11.2+ -- HashiCorp Consul Helm chart 0.41.0+ +Refer to the [Technical Specifications](/docs/api-gateway/api-gateway-tech-specs) page for minimum software requirements. ## Installation From a9b5eeb58e419a504fc018f828e0d8dfe0065003 Mon Sep 17 00:00:00 2001 From: Nathan Coleman Date: Tue, 22 Feb 2022 17:56:50 -0500 Subject: [PATCH 20/40] Adjust naming convention within api-gateway path --- website/content/docs/api-gateway/{api-gateway.mdx => index.mdx} | 2 +- .../api-gateway/{api-gateway-tech-specs.mdx => tech-specs.mdx} | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename website/content/docs/api-gateway/{api-gateway.mdx => index.mdx} (99%) rename website/content/docs/api-gateway/{api-gateway-tech-specs.mdx => tech-specs.mdx} (100%) diff --git a/website/content/docs/api-gateway/api-gateway.mdx b/website/content/docs/api-gateway/index.mdx similarity index 99% rename from website/content/docs/api-gateway/api-gateway.mdx rename to website/content/docs/api-gateway/index.mdx index 3c84c8b597..d037e48ec7 100644 --- a/website/content/docs/api-gateway/api-gateway.mdx +++ b/website/content/docs/api-gateway/index.mdx @@ -20,7 +20,7 @@ Consul API Gateway implements the Kubernetes [Gateway API Specification](https:/ ## Requirements -Refer to the [Technical Specifications](/docs/api-gateway/api-gateway-tech-specs) page for minimum software requirements. +Refer to the [Technical Specifications](/docs/api-gateway/tech-specs) page for minimum software requirements. ## Installation diff --git a/website/content/docs/api-gateway/api-gateway-tech-specs.mdx b/website/content/docs/api-gateway/tech-specs.mdx similarity index 100% rename from website/content/docs/api-gateway/api-gateway-tech-specs.mdx rename to website/content/docs/api-gateway/tech-specs.mdx From 2d0e16c5e21127cd27ff6829bf1bcc14139a532c Mon Sep 17 00:00:00 2001 From: Nathan Coleman Date: Tue, 22 Feb 2022 18:02:53 -0500 Subject: [PATCH 21/40] Adjust navigation for Consul API Gateway --- website/data/docs-nav-data.json | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 5bee60376d..51077a327b 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -373,18 +373,18 @@ "hidden": true } ] - }, + }, { "title": "Consul API Gateway", "routes": [ { - "title": "Consul API Gateway", - "path": "api-gateway/api-gateway" + "title": "Overview", + "path": "api-gateway" }, { "title": "Technical Specifications", - "path": "api-gateway/api-gateway-tech-specs" - } + "path": "api-gateway/tech-specs" + } ] }, { From 88e4880267d7c032c7b54f888f3417bd926023bf Mon Sep 17 00:00:00 2001 From: Nathan Coleman Date: Tue, 22 Feb 2022 19:02:00 -0500 Subject: [PATCH 22/40] Remove metrics port from documentation We've decided not to include this configurable in the Helm chart at this time --- website/content/docs/api-gateway/tech-specs.mdx | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/website/content/docs/api-gateway/tech-specs.mdx b/website/content/docs/api-gateway/tech-specs.mdx index 12245b1848..c9d0a617fe 100644 --- a/website/content/docs/api-gateway/tech-specs.mdx +++ b/website/content/docs/api-gateway/tech-specs.mdx @@ -61,10 +61,9 @@ The tables below list the TCP ports that are used by each component of the API G ### Gateway Controller Pod -| Port | Used For | -| ---- | ------------------------------------------------------------------ | -| 9090 | Secret Discovery Service (SDS) | -| Configurable | Port for scraping Prometheus metrics. Disabled by default. | +| Port | Used For s | +| ---- | ------------------------------ | +| 9090 | Secret Discovery Service (SDS) | ### Gateway Instance Pod From 484bb5c59d437fe78fd504791ec87244164ead12 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Tue, 22 Feb 2022 16:44:30 -0800 Subject: [PATCH 23/40] separated overview content and usage content into their own pages --- website/content/docs/api-gateway/index.mdx | 316 +----------------- .../content/docs/api-gateway/tech-specs.mdx | 50 ++- website/data/docs-nav-data.json | 4 + 3 files changed, 36 insertions(+), 334 deletions(-) diff --git a/website/content/docs/api-gateway/index.mdx b/website/content/docs/api-gateway/index.mdx index d037e48ec7..f433ea6515 100644 --- a/website/content/docs/api-gateway/index.mdx +++ b/website/content/docs/api-gateway/index.mdx @@ -1,324 +1,28 @@ --- layout: docs -page_title: API Gateway +page_title: Consul API Gateway Overview description: >- Using Consul API gateway functionality --- -# Consul API Gateway +# Consul API Gateway Overview -This topic describes how to use the Consul API Gateway add-on module, which helps users control access to services running within a Consul service mesh. The API gateway enables external network clients to access applications and services running in a Consul datacenter. This type of network traffic is commonly referred to as "north-south" network traffic as it refers to the flow of data into and out of a specific environment. Requests from clients can also be forwarded based on path or request protocol. +This topic provides an overview of the Consul API Gateway. -You can learn more about using Consul API Gateway by completing the [Consul API Gateway tutorial](https://learn.hashicorp.com/tutorials/consul/kubernetes-api-gateway). +## What is Consul API Gateway? -## Introduction +Consul API Gateway is an add-on for Consul that helps users control access to services running within a Consul service mesh. The API gateway enables external network clients to access applications and services running in a Consul datacenter. This type of network traffic is commonly referred to as "north-south" network traffic as it refers to the flow of data into and out of a specific environment. Requests from clients can also be forwarded based on path or request protocol. -Consul API Gateway implements the Kubernetes [Gateway API Specification](https://gateway-api.sigs.k8s.io/). This specification defines a set of custom resource definitions (CRD) that can create logical gateways and routes based on the path or protocol of a client request. Consul API Gateway solves two primary use cases: +Consul API Gateway solves the following primary use cases: - **Controlling access at the point of entry**: Consul API Gateway allows users to set the protocols of external connection requests and provide clients with TLS certificates from trusted providers (e.g., Verisign, Let’s Encrypt). - **Simplifying traffic management**: The Consul API Gateway can load balance requests across services and route traffic to the appropriate service by matching one or more criteria, such as hostname, path, header presence or value, and HTTP Method type (e.g., GET, POST, PATCH). -## Requirements +## Implementation -Refer to the [Technical Specifications](/docs/api-gateway/tech-specs) page for minimum software requirements. +Consul API Gateway implements the Kubernetes [Gateway API Specification](https://gateway-api.sigs.k8s.io/). This specification defines a set of custom resource definitions (CRD) that can create logical gateways and routes based on the path or protocol of a client request. -## Installation +## Additional Resources -1. Issue the following command to install the CRDs: +You can learn more about using Consul API Gateway by completing the [Consul API Gateway tutorial](https://learn.hashicorp.com/tutorials/consul/kubernetes-api-gateway). - - - ```shell-session - $ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?ref=v0.1.0" - ``` - - - -1. Create a `values.yaml` file for your Consul API Gateway deployment. Copy the content below into the `values.yaml` file. The `values.yaml` will be used by the Consul Helm chart. See [Helm Chart Configuration - apigateway](https://www.consul.io/docs/k8s/helm#apigateway) for more available options on how to configure your Consul API Gateway deployment via the Helm chart. - - - - ```yaml - global: - name: consul - image: 'hashicorp/consul:1.11.2' - connectInject: - enabled: true - controller: - enabled: true - apiGateway: - enabled: true - image: hashicorp/consul-api-gateway:0.1.0 - ``` - - - -1. Install Consul API Gateway using the standard Consul Helm chart and specify the custom values file. - - - - ```shell-session - $ helm install consul hashicorp/consul --version 0.41.0 --values values.yaml - ``` - - - -## Usage - -1. Verify that the [requirements](#requirements) have been met. -1. Verify that the Consul API Gateway CRDs and controller have been installed and applied (see [Installation](#installation)). -1. Configure the artifacts described below in [Configuration](#configuration). If the following config is added to the `values.yaml` Helm config, the GatewayClassConfig and GatewayClass will be created automatically, and only the Gateway, Listeners and Routes will need to be configured manually. The [`serviceType`](https://www.consul.io/docs/k8s/helm#v-apigateway-managedgatewayclass-servicetype) for a managed GatewayClass will default to `LoadBalancer`, which is appropriate for most deployments to managed Kubernetes cloud offerings (EKS, GKE, AKS) - other deployments, such as to a [kind](https://kind.sigs.k8s.io/) cluster, may require specifying `NodePort` or `ClusterIP` instead. - - - - ```yaml - apiGateway: - managedGatewayClass: - enabled: true - ``` - - - -1. Issue the `kubectl apply` command to implement the configurations, e.g.: - - - - ```shell-session - $ kubectl apply -f gateway.yaml routes.yaml - ``` - - - - - -## Configuration - -Configure the following artifacts to facilitate ingress into your Consul service mesh: - -- [GatewayClassConfig](#gatewayclassconfig): Describes additional Consul API Gateway-related configuration parameters for the `GatewayClass` resource. -- [GatewayClass](#gatewayclass): Defines a class of gateway resources that you can use as a template for creating gateways. -- [Gateway](#gateway): Defines the main infrastructure resource that links API gateway components. It specifies the name of the `GatewayClass` and one or more `listeners` (see [Listeners](#listeners)), which specify the logical endpoints bound to the gateway's addresses. -- [Routes](#routes): Specifies the path from the client to the listener. - -### GatewayClassConfig - -The `GatewayClassConfig` object describes Consul API Gateway-related configuration parameters for the [`GatewayClass`](#gatewayclass). - -Add the `kind: GatewayClassConfig` option to the gateway values file to declare a gateway class. -The following example creates a gateway class config called `test-gateway-class-config`: - - - -```yaml -apiVersion: api-gateway.consul.hashicorp.com/v1alpha1 -kind: GatewayClassConfig -metadata: - name: test-gateway-class-config -spec: - useHostPorts: true - logLevel: 'trace' - consul: - scheme: 'https' - ports: - http: 8501 - grpc: 8502 -``` - - - -The following table describes the allowed parameters for the `spec` array: - -| Parameter | Description | Type | Default | -| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------ | -| `consul.address` | Specifies the address of the Consul server to communicate with in the gateway pod. If unspecified, the pod will attempt to use a local agent on the host on which the pod is running. | String | N/A | -| `consul.authentication.account` | Specifies the Kubernetes service account to use for authentication. | String | N/A | -| `consul.authentication.managed` | Set to `true` to enable deployments to run with managed service accounts created by the gateway controller. The `consul.authentication.account` field is ignored when this option is enabled. | Boolean | `false` | -| `consul.authentication.method` | Specifies the Consul auth method used for initial authentication by Consul API Gateway. | String | N/A | -| `consul.authentication.namespace` | Specifies the Consul namespace to use for authentication. | String | N/A | -| `consul.ports.grpc` | Specifies the gRPC port for Consul's xDS server. | Integer | `8502` | -| `consul.ports.http` | Specifies the port for Consul's HTTP server. | Integer | `8500` | -| `consul.scheme` | Specifies the scheme to use for connecting to Consul. The supported values are `"http"` and `"https"`. | String | `"http"` | -| `copyAnnotations.service` | List of annotations to copy to the gateway service. | Array | `["external-dns.alpha.kubernetes.io/hostname"]` | -| `image.consulAPIGateway` | The image to use for consul-api-gateway. View available image tags on [DockerHub](https://hub.docker.com/r/hashicorp/consul-api-gateway/tags). | String | `"hashicorp/consul-api-gateway:RELEASE_VERSION"` | -| `image.envoy` | Specifies the container image to use for Envoy. View available image tags on [DockerHub](https://hub.docker.com/r/envoyproxy/envoy/tags). | String | `"envoyproxy/envoy:RELEASE_VERSION"` | -| `logLevel` | Specifies the error reporting level for logs. You can specify the following values: `error`, `warning`, `info`, `debug`, `trace`. | String | `"info"` | -| `nodeSelector` | Specifies a set of parameters that constrain the nodes on which the pod can run. Defining nodes with the `nodeSelector` enables the pod to fit on a node. The selector must match a node's labels for the pod to be scheduled on that node. Refer to the [Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/) for additional information. | Object | N/A | -| `serviceType` | Specifies the ingress methods for a service. The following values are supported:
`ClusterIP`
`NodePort`
`LoadBalancer`. | String | N/A | -| `useHostPorts` | If set to `true`, then the Envoy container ports are mapped to host ports. | Boolean | `false` | - -Refer to the [Consul API Gateway repository](https://github.com/hashicorp/consul-api-gateway/blob/main/config/crd/bases/api-gateway.consul.hashicorp.com_gatewayclassconfigs.yaml) for the complete specification. - -### GatewayClass - -The `GatewayClass` resource is used as a template for creating `Gateway` resources. -The specification includes the name of the controller (`controllerName`) and an API object containing controller-specific configuration resources within the cluster (`parametersRef`). -The value of the `controllerName` field must be set to `hashicorp.com/consul-api-gateway-controller`. - -When gateways are created from a `GatewayClass`, they use the parameters specified in the `GatewayClass` at the time of instantiation. - -Add the `kind: GatewayClass` option to the the gateway values file to declare a gateway class. -The following example creates a gateway class called `test-gateway-class`: - - - -```yaml -apiVersion: gateway.networking.k8s.io/v1alpha2 -kind: GatewayClass -metadata: - name: test-gateway-class -spec: - controllerName: 'hashicorp.com/consul-api-gateway-controller' - parametersRef: - group: api-gateway.consul.hashicorp.com - kind: GatewayClassConfig - name: test-gateway-class-config -``` - - - -Refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.GatewayClass) for details about configuring gateway classes. - -### Gateway - -The gateway configuration is the main infrastructure resource that links API gateway components. It specifies the name of the `GatewayClass` and one or more `listeners`. - -Add the `kind: Gateway` option to the configuration file to declare a gateway. -The following example creates a gateway called `example-gateway`. -The gateway is based on the `test-gateway-class` and includes a listener called `https` (see [Listeners](#listeners) for details about the `listener` configuration). - - - -```yaml -apiVersion: gateway.networking.k8s.io/v1alpha2 -kind: Gateway -metadata: - name: example-gateway - annotations: - 'external-dns.alpha.kubernetes.io/hostname': DNS_HOSTNAME -spec: - gatewayClassName: test-gateway-class - listeners: - - protocol: HTTPS - hostname: DNS_HOSTNAME - port: 443 - name: https - allowedRoutes: - namespaces: - from: Same - tls: - certificateRefs: - - name: gateway-production-certificate -``` - - - -Refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.Gateway) for details about configuring gateways: - -#### Listeners - -Listeners are the logical endpoints bound to the gateway's addresses. -Add the `listener` object to the `gateway` configuration and specify the following properties to define a listener: - -| Parameter | Description | Type | Default | -| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------- | -| `hostname` | Specifies the virtual hostname to match for protocol types. | String | none | -| `port` | Specifies the network port number. | Integer | none | -| `protocol` | Specifies the network protocol expected by the listener. | String | `http` | -| `tls` | Collection of parameters that specify TLS options for the listener. Refer to the [`GatewayTLSConfig`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.GatewayTLSConfig) documentation for additional information about configuring TLS. | Object | N/A | -| `tls.mode` | Specifies a mode for operating Consul API Gateway listeners over TLS.
You can only specify the `Terminate` mode, which configures the TLS session between the downstream client and the gateway to terminate at the gateway.
Refer to the [`TLSModeType` documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.TLSModeType) for additional information. | String | `Terminate` | -| `tls.certificateRefs` | Specifies the name of secret object used for Envoy SDS (Secret Discovery Service) to support terminating TLS. Refer to the [`[]*SecretObjectReference` documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.SecretObjectReference) for additional information. | String | N/A | -| `tls.options` | Specifies key/value pairs to enable extended TLS configuration specific to an implementation. | Object | N/A | -| `tls.options.tls_min_version` | Specifies the minimum TLS version supported for the listener. The following values are supported: `TLS_AUTO`, `TLSv1_0`, `TLSv1_1`, `TLSv1_2`, `TLSv1_3`. | String | `TLS 1.2` | -| `tls.options.tls_max_version` | Specifies the maximum TLS version supported for the listener. The specified version must be greater than or equal to `TLSMinVersion`. The following values are supported: `TLS_AUTO`, `TLSv1_0`, `TLSv1_1`, `TLSv1_2`, `TLSv1_3`. | String | `TLS 1.3` | -| `tls.options.tls_cipher_suites` | Specifies the list of TLS cipher suites to support when negotiating connections using TLS 1.2 or earlier.
If unspecified, a [more secure set of cipher suites](https://github.com/hashicorp/consul-api-gateway/blob/main/internal/common/tls.go#L3-L10) than Envoy's current [default server cipher list](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/transport_sockets/tls/v3/common.proto#envoy-v3-api-field-extensions-transport-sockets-tls-v3-tlsparameters-cipher-suites) will be used.
The full list of supported cipher suites can seen in [`internal/common/tls.go`](https://github.com/hashicorp/consul-api-gateway/blob/main/internal/common/tls.go) and is dependent on underlying support in Envoy. | String | See description | - -Refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.Listener) for details about configuring listeners. - -### Route - -Routes are independent configuration objects that are associated with specific listeners. - -Declare a route with either `kind: HTTPRoute` or `kind: TCPRoute` and configure the route parameters in the `spec` block. -Refer to the Kubernetes Gateway API documentation for each object type for details: - -- [HTTPRoute](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.HTTPRoute) -- [TCPRoute](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.TCPRoute) - -The following example creates a route named `example-route` associated with a listener defined in `example-gateway`. - - - -```yaml -apiVersion: gateway.networking.k8s.io/v1alpha2 -kind: HTTPRoute -metadata: - name: example-route -spec: - parentRefs: - - name: example-gateway - rules: - - backendRefs: - - kind: Service - name: echo - port: 8080 -``` - - - - -### MeshService - -MeshService holds a reference to an externally managed Consul Service Mesh service, and can be used as a `backendRef` for a [`Route`](#route). - -| Parameter | Description | Type | Default | -| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------- | -| `name` | Specifies the service name for a Consul service. It is assumed this service will exist in either the `consulDestinationNamespace` or mirrored Consul namespace from where this custom resource is defined, depending on the Helm configuration. - -Refer to the [Consul API Gateway repository](https://github.com/hashicorp/consul-api-gateway/blob/main/config/crd/bases/api-gateway.consul.hashicorp.com_meshservices.yaml) for the complete specification. diff --git a/website/content/docs/api-gateway/tech-specs.mdx b/website/content/docs/api-gateway/tech-specs.mdx index 12245b1848..eb5639dd28 100644 --- a/website/content/docs/api-gateway/tech-specs.mdx +++ b/website/content/docs/api-gateway/tech-specs.mdx @@ -7,7 +7,13 @@ description: >- # Technical Specifications -## Required Software and Supported Versions +This topic describes the technical specifications associated with using Consul API Gateway. + +## Requirements + +Verify that your environment meets the following requirements prior to using Consul API Gateway. + +### Datacenter Requirements Your datacenter must meet the following requirements prior to configuring the Consul API Gateway: @@ -16,6 +22,16 @@ Your datacenter must meet the following requirements prior to configuring the Co - Consul 1.11.2+ - HashiCorp Consul Helm chart 0.41.0+ +### TCP Port Requirements + +The following table describes the TCP port requirements for each component of the API Gateway. + +| Port | Description | Component | +| ---- | ----------- | --------- | +| 9090 | Secret discovery service (SDS) | Gateway controller pod
Gateway instance pod | +| 20000 | Kubernetes readiness probe | Gateway instance pod | +| Configurable | Port for scraping Prometheus metrics. Disabled by default. | Gateway controller pod | + ## Consul Server Deployments - Consul Editions supported: OSS and Enterprise @@ -39,36 +55,14 @@ Supported version of the Gateway API spec: v1alpha2 ## Resource Allocations -The tables below list the resource allocations for each component of the API Gateway. +The following resources are allocated for each component of the API Gateway. ### Gateway Controller Pod -| Resource | Allocation | -| -------- | -------------------------------------------------------------------------------------------------------- | -| CPU | None specified. Will use namespace or cluster default depending on the Kubernetes cluster configuration. | -| Memory | None specified. Will use namespace or cluster default depending on the Kubernetes cluster configuration. | +* **CPU**: None. Either the namespace or cluster default is allocated, depending on the Kubernetes cluster configuration. +* **Memory**: None. Either the the namespace or cluster default is allocated, depending on the Kubernetes cluster configuration. ### Gateway Instance Pod -| Resource | Allocation | -| -------- | -------------------------------------------------------------------------------------------------------- | -| CPU | None specified. Will use namespace or cluster default depending on the Kubernetes cluster configuration. | -| Memory | None specified. Will use namespace or cluster default depending on the Kubernetes cluster configuration. | - -## TCP Ports Required - -The tables below list the TCP ports that are used by each component of the API Gateway. - -### Gateway Controller Pod - -| Port | Used For | -| ---- | ------------------------------------------------------------------ | -| 9090 | Secret Discovery Service (SDS) | -| Configurable | Port for scraping Prometheus metrics. Disabled by default. | - -### Gateway Instance Pod - -| Port | Used For | -| ----- | ----------------------------- | -| 9090 | Secret Discovery Service (SDS) | -| 20000 | Kubernetes readiness probe | +* **CPU**: None. Either the namespace or cluster default is allocated, depending on the Kubernetes cluster configuration. +* **Memory**: None. Either the namespace or cluster default is allocated, depending on the Kubernetes cluster configuration. \ No newline at end of file diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 51077a327b..0130d1f472 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -381,6 +381,10 @@ "title": "Overview", "path": "api-gateway" }, + { + "title": "Usage", + "path": "api-gateway/api-gateway-usage" + }, { "title": "Technical Specifications", "path": "api-gateway/tech-specs" From 187ab6948b4fea31e3208ccf233a035ee61dc453 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Tue, 22 Feb 2022 16:46:11 -0800 Subject: [PATCH 24/40] forgot to include the usage page in the last commit --- .../docs/api-gateway/api-gateway-usage.mdx | 315 ++++++++++++++++++ 1 file changed, 315 insertions(+) create mode 100644 website/content/docs/api-gateway/api-gateway-usage.mdx diff --git a/website/content/docs/api-gateway/api-gateway-usage.mdx b/website/content/docs/api-gateway/api-gateway-usage.mdx new file mode 100644 index 0000000000..d901c2540c --- /dev/null +++ b/website/content/docs/api-gateway/api-gateway-usage.mdx @@ -0,0 +1,315 @@ +--- +layout: docs +page_title: Consul API Gateway Usage +description: >- + Using Consul API gateway functionality +--- + +# Consul API Gateway Usage + +This topic describes how to use the Consul API Gateway add-on module. It includes instructions for installation and configuration. + +## Requirements + +Refer to [Technical Specifications](/docs/api-gateway/tech-specs) for minimum software requirements. + +## Installation + +1. Issue the following command to install the CRDs: + + + + ```shell-session + $ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?ref=v0.1.0" + ``` + + + +1. Create a `values.yaml` file for your Consul API Gateway deployment. Copy the content below into the `values.yaml` file. The `values.yaml` will be used by the Consul Helm chart. See [Helm Chart Configuration - apigateway](https://www.consul.io/docs/k8s/helm#apigateway) for more available options on how to configure your Consul API Gateway deployment via the Helm chart. + + + + ```yaml + global: + name: consul + image: 'hashicorp/consul:1.11.2' + connectInject: + enabled: true + controller: + enabled: true + apiGateway: + enabled: true + image: hashicorp/consul-api-gateway:0.1.0 + ``` + + + +1. Install Consul API Gateway using the standard Consul Helm chart and specify the custom values file. + + + + ```shell-session + $ helm install consul hashicorp/consul --version 0.41.0 --values values.yaml + ``` + + + +## Usage + +1. Verify that the [requirements](#requirements) have been met. +1. Verify that the Consul API Gateway CRDs and controller have been installed and applied (see [Installation](#installation)). +1. Configure the artifacts described below in [Configuration](#configuration). If the following config is added to the `values.yaml` Helm config, the GatewayClassConfig and GatewayClass will be created automatically, and only the Gateway, Listeners and Routes will need to be configured manually. The [`serviceType`](https://www.consul.io/docs/k8s/helm#v-apigateway-managedgatewayclass-servicetype) for a managed GatewayClass will default to `LoadBalancer`, which is appropriate for most deployments to managed Kubernetes cloud offerings (EKS, GKE, AKS) - other deployments, such as to a [kind](https://kind.sigs.k8s.io/) cluster, may require specifying `NodePort` or `ClusterIP` instead. + + + + ```yaml + apiGateway: + managedGatewayClass: + enabled: true + ``` + + + +1. Issue the `kubectl apply` command to implement the configurations, e.g.: + + + + ```shell-session + $ kubectl apply -f gateway.yaml routes.yaml + ``` + + + + + +## Configuration + +Configure the following artifacts to facilitate ingress into your Consul service mesh: + +- [GatewayClassConfig](#gatewayclassconfig): Describes additional Consul API Gateway-related configuration parameters for the `GatewayClass` resource. +- [GatewayClass](#gatewayclass): Defines a class of gateway resources that you can use as a template for creating gateways. +- [Gateway](#gateway): Defines the main infrastructure resource that links API gateway components. It specifies the name of the `GatewayClass` and one or more `listeners` (see [Listeners](#listeners)), which specify the logical endpoints bound to the gateway's addresses. +- [Routes](#routes): Specifies the path from the client to the listener. + +### GatewayClassConfig + +The `GatewayClassConfig` object describes Consul API Gateway-related configuration parameters for the [`GatewayClass`](#gatewayclass). + +Add the `kind: GatewayClassConfig` option to the gateway values file to declare a gateway class. +The following example creates a gateway class config called `test-gateway-class-config`: + + + +```yaml +apiVersion: api-gateway.consul.hashicorp.com/v1alpha1 +kind: GatewayClassConfig +metadata: + name: test-gateway-class-config +spec: + useHostPorts: true + logLevel: 'trace' + consul: + scheme: 'https' + ports: + http: 8501 + grpc: 8502 +``` + + + +The following table describes the allowed parameters for the `spec` array: + +| Parameter | Description | Type | Default | +| --- | --- | ---- | ------- | +| `consul.address` | Specifies the address of the Consul server to communicate with in the gateway pod. If unspecified, the pod will attempt to use a local agent on the host on which the pod is running. | String | N/A | +| `consul.authentication.account` | Specifies the Kubernetes service account to use for authentication. | String | N/A | +| `consul.authentication.managed` | Set to `true` to enable deployments to run with managed service accounts created by the gateway controller. The `consul.authentication.account` field is ignored when this option is enabled. | Boolean | `false` | +| `consul.authentication.method` | Specifies the Consul auth method used for initial authentication by Consul API Gateway. | String | N/A | +| `consul.authentication.namespace` | Specifies the Consul namespace to use for authentication. | String | N/A | +| `consul.ports.grpc` | Specifies the gRPC port for Consul's xDS server. | Integer | `8502` | +| `consul.ports.http` | Specifies the port for Consul's HTTP server. | Integer | `8500` | +| `consul.scheme` | Specifies the scheme to use for connecting to Consul. The supported values are `"http"` and `"https"`. | String | `"http"` | +| `copyAnnotations.service` | List of annotations to copy to the gateway service. | Array | `["external-dns.alpha.kubernetes.io/hostname"]` | +| `image.consulAPIGateway` | The image to use for consul-api-gateway. View available image tags on [DockerHub](https://hub.docker.com/r/hashicorp/consul-api-gateway/tags). | String | `"hashicorp/consul-api-gateway:RELEASE_VERSION"` | +| `image.envoy` | Specifies the container image to use for Envoy. View available image tags on [DockerHub](https://hub.docker.com/r/envoyproxy/envoy/tags). | String | `"envoyproxy/envoy:RELEASE_VERSION"` | +| `logLevel` | Specifies the error reporting level for logs. You can specify the following values: `error`, `warning`, `info`, `debug`, `trace`. | String | `"info"` | +| `nodeSelector` | Specifies a set of parameters that constrain the nodes on which the pod can run. Defining nodes with the `nodeSelector` enables the pod to fit on a node. The selector must match a node's labels for the pod to be scheduled on that node. Refer to the [Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/) for additional information. | Object | N/A | +| `serviceType` | Specifies the ingress methods for a service. The following values are supported:
`ClusterIP`
`NodePort`
`LoadBalancer`. | String | N/A | +| `useHostPorts` | If set to `true`, then the Envoy container ports are mapped to host ports. | Boolean | `false` | + +Refer to the [Consul API Gateway repository](https://github.com/hashicorp/consul-api-gateway/blob/main/config/crd/bases/api-gateway.consul.hashicorp.com_gatewayclassconfigs.yaml) for the complete specification. + +### GatewayClass + +The `GatewayClass` resource is used as a template for creating `Gateway` resources. +The specification includes the name of the controller (`controllerName`) and an API object containing controller-specific configuration resources within the cluster (`parametersRef`). +The value of the `controllerName` field must be set to `hashicorp.com/consul-api-gateway-controller`. + +When gateways are created from a `GatewayClass`, they use the parameters specified in the `GatewayClass` at the time of instantiation. + +Add the `kind: GatewayClass` option to the the gateway values file to declare a gateway class. +The following example creates a gateway class called `test-gateway-class`: + + + +```yaml +apiVersion: gateway.networking.k8s.io/v1alpha2 +kind: GatewayClass +metadata: + name: test-gateway-class +spec: + controllerName: 'hashicorp.com/consul-api-gateway-controller' + parametersRef: + group: api-gateway.consul.hashicorp.com + kind: GatewayClassConfig + name: test-gateway-class-config +``` + + + +Refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.GatewayClass) for details about configuring gateway classes. + +### Gateway + +The gateway configuration is the main infrastructure resource that links API gateway components. It specifies the name of the `GatewayClass` and one or more `listeners`. + +Add the `kind: Gateway` option to the configuration file to declare a gateway. +The following example creates a gateway called `example-gateway`. +The gateway is based on the `test-gateway-class` and includes a listener called `https` (see [Listeners](#listeners) for details about the `listener` configuration). + + + +```yaml +apiVersion: gateway.networking.k8s.io/v1alpha2 +kind: Gateway +metadata: + name: example-gateway + annotations: + 'external-dns.alpha.kubernetes.io/hostname': DNS_HOSTNAME +spec: + gatewayClassName: test-gateway-class + listeners: + - protocol: HTTPS + hostname: DNS_HOSTNAME + port: 443 + name: https + allowedRoutes: + namespaces: + from: Same + tls: + certificateRefs: + - name: gateway-production-certificate +``` + + + +Refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.Gateway) for details about configuring gateways: + +#### Listeners + +Listeners are the logical endpoints bound to the gateway's addresses. +Add the `listener` object to the `gateway` configuration and specify the following properties to define a listener: + +| Parameter | Description | Type | Default | +| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------- | +| `hostname` | Specifies the virtual hostname to match for protocol types. | String | none | +| `port` | Specifies the network port number. | Integer | none | +| `protocol` | Specifies the network protocol expected by the listener. | String | `http` | +| `tls` | Collection of parameters that specify TLS options for the listener. Refer to the [`GatewayTLSConfig`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.GatewayTLSConfig) documentation for additional information about configuring TLS. | Object | N/A | +| `tls.mode` | Specifies a mode for operating Consul API Gateway listeners over TLS.
You can only specify the `Terminate` mode, which configures the TLS session between the downstream client and the gateway to terminate at the gateway.
Refer to the [`TLSModeType` documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.TLSModeType) for additional information. | String | `Terminate` | +| `tls.certificateRefs` | Specifies the name of secret object used for Envoy SDS (Secret Discovery Service) to support terminating TLS. Refer to the [`[]*SecretObjectReference` documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.SecretObjectReference) for additional information. | String | N/A | +| `tls.options` | Specifies key/value pairs to enable extended TLS configuration specific to an implementation. | Object | N/A | +| `tls.options.tls_min_version` | Specifies the minimum TLS version supported for the listener. The following values are supported: `TLS_AUTO`, `TLSv1_0`, `TLSv1_1`, `TLSv1_2`, `TLSv1_3`. | String | `TLS 1.2` | +| `tls.options.tls_max_version` | Specifies the maximum TLS version supported for the listener. The specified version must be greater than or equal to `TLSMinVersion`. The following values are supported: `TLS_AUTO`, `TLSv1_0`, `TLSv1_1`, `TLSv1_2`, `TLSv1_3`. | String | `TLS 1.3` | +| `tls.options.tls_cipher_suites` | Specifies the list of TLS cipher suites to support when negotiating connections using TLS 1.2 or earlier.
If unspecified, a [more secure set of cipher suites](https://github.com/hashicorp/consul-api-gateway/blob/main/internal/common/tls.go#L3-L10) than Envoy's current [default server cipher list](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/transport_sockets/tls/v3/common.proto#envoy-v3-api-field-extensions-transport-sockets-tls-v3-tlsparameters-cipher-suites) will be used.
The full list of supported cipher suites can seen in [`internal/common/tls.go`](https://github.com/hashicorp/consul-api-gateway/blob/main/internal/common/tls.go) and is dependent on underlying support in Envoy. | String | See description | + +Refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.Listener) for details about configuring listeners. + +### Route + +Routes are independent configuration objects that are associated with specific listeners. + +Declare a route with either `kind: HTTPRoute` or `kind: TCPRoute` and configure the route parameters in the `spec` block. +Refer to the Kubernetes Gateway API documentation for each object type for details: + +- [HTTPRoute](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.HTTPRoute) +- [TCPRoute](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.TCPRoute) + +The following example creates a route named `example-route` associated with a listener defined in `example-gateway`. + + + +```yaml +apiVersion: gateway.networking.k8s.io/v1alpha2 +kind: HTTPRoute +metadata: + name: example-route +spec: + parentRefs: + - name: example-gateway + rules: + - backendRefs: + - kind: Service + name: echo + port: 8080 +``` + + + + +### MeshService + +MeshService holds a reference to an externally managed Consul Service Mesh service, and can be used as a `backendRef` for a [`Route`](#route). + +| Parameter | Description | Type | Default | +| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------- | +| `name` | Specifies the service name for a Consul service. It is assumed this service will exist in either the `consulDestinationNamespace` or mirrored Consul namespace from where this custom resource is defined, depending on the Helm configuration. + +Refer to the [Consul API Gateway repository](https://github.com/hashicorp/consul-api-gateway/blob/main/config/crd/bases/api-gateway.consul.hashicorp.com_meshservices.yaml) for the complete specification. From 51225a3476fe174001c5dc8762b5a2bd097d43be Mon Sep 17 00:00:00 2001 From: Andrew Stucki Date: Wed, 23 Feb 2022 11:15:58 -0500 Subject: [PATCH 25/40] Add k8s features --- .../docs/api-gateway/kubernetes-features.mdx | 19 +++++++++++++++++++ website/data/docs-nav-data.json | 4 ++++ 2 files changed, 23 insertions(+) create mode 100644 website/content/docs/api-gateway/kubernetes-features.mdx diff --git a/website/content/docs/api-gateway/kubernetes-features.mdx b/website/content/docs/api-gateway/kubernetes-features.mdx new file mode 100644 index 0000000000..5a6ac52383 --- /dev/null +++ b/website/content/docs/api-gateway/kubernetes-features.mdx @@ -0,0 +1,19 @@ +--- +layout: docs +page_title: Consul API Gateway Supported Kubernetes Features +description: >- + Consul API Gateway Supported Kubernetes Features. +--- + +# Consul API Gateway - Gateway Spec Features + +The Consul API Gateway currently supports a subset of the [v1alpha2 Gateway API Spec](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/). The table below +specifies the supported features of the spec. For a full list of features, including the list of gateway and route statuses and an explanation on how they +are used, see the [in-repo documentation](https://github.com/hashicorp/consul-api-gateway/blob/main/dev/docs/supported-features.md). + +| Kubernetes Object | Features | +| ----- | ----------------------------- | +| `GatewayClass` |
  • Parameter specification via `GatewayClassConfig` CRD
  • Controller matching on `"hashicorp.com/consul-api-gateway-controller"`
| +| `Gateway` |
  • Supported protocols: `HTTP`, `HTTPS`, `TCP`
  • Header-based hostname matching (no SNI support)
  • Supported filters: header addition, removal, and setting
  • TLS modes supported: `terminate`
  • Certificate types supported: `core/v1/Secret`
  • Extended options: TLS version and cipher constraints
| +| `HTTPRoute` |
  • Weight-based load balancing
  • Supported rules: path, header, query, and method-based matching
  • Supported filters: header addition, removal, and setting
  • Supported backend types:
    1. `core/v1/Service` (must map to a registered Consul service)
    2. `api-gateway.consul.hashicorp.com/v1alpha1/MeshService`
| +| `TCPRoute` |
  • Supported backend types:
    1. `core/v1/Service` (must map to a registered Consul service)
    2. `api-gateway.consul.hashicorp.com/v1alpha1/MeshService`
| \ No newline at end of file diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 51077a327b..a18c3be902 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -384,6 +384,10 @@ { "title": "Technical Specifications", "path": "api-gateway/tech-specs" + }, + { + "title": "Supported Kubernetes Features", + "path": "api-gateway/kubernetes-features" } ] }, From 1c3cdfc39cb0ef94f16d144874ec80c531458803 Mon Sep 17 00:00:00 2001 From: Andrew Stucki Date: Wed, 23 Feb 2022 11:26:51 -0500 Subject: [PATCH 26/40] Add links to sections of the spec --- website/content/docs/api-gateway/kubernetes-features.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/website/content/docs/api-gateway/kubernetes-features.mdx b/website/content/docs/api-gateway/kubernetes-features.mdx index 5a6ac52383..10e66f9619 100644 --- a/website/content/docs/api-gateway/kubernetes-features.mdx +++ b/website/content/docs/api-gateway/kubernetes-features.mdx @@ -13,7 +13,7 @@ are used, see the [in-repo documentation](https://github.com/hashicorp/consul-ap | Kubernetes Object | Features | | ----- | ----------------------------- | -| `GatewayClass` |
  • Parameter specification via `GatewayClassConfig` CRD
  • Controller matching on `"hashicorp.com/consul-api-gateway-controller"`
| -| `Gateway` |
  • Supported protocols: `HTTP`, `HTTPS`, `TCP`
  • Header-based hostname matching (no SNI support)
  • Supported filters: header addition, removal, and setting
  • TLS modes supported: `terminate`
  • Certificate types supported: `core/v1/Secret`
  • Extended options: TLS version and cipher constraints
| -| `HTTPRoute` |
  • Weight-based load balancing
  • Supported rules: path, header, query, and method-based matching
  • Supported filters: header addition, removal, and setting
  • Supported backend types:
    1. `core/v1/Service` (must map to a registered Consul service)
    2. `api-gateway.consul.hashicorp.com/v1alpha1/MeshService`
| -| `TCPRoute` |
  • Supported backend types:
    1. `core/v1/Service` (must map to a registered Consul service)
    2. `api-gateway.consul.hashicorp.com/v1alpha1/MeshService`
| \ No newline at end of file +| [`GatewayClass`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.GatewayClass) |
  • Parameter specification via `GatewayClassConfig` CRD
  • Controller matching on `"hashicorp.com/consul-api-gateway-controller"`
| +| [`Gateway`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.Gateway) |
  • Supported protocols: `HTTP`, `HTTPS`, `TCP`
  • Header-based hostname matching (no SNI support)
  • Supported filters: header addition, removal, and setting
  • TLS modes supported: `terminate`
  • Certificate types supported: `core/v1/Secret`
  • Extended options: TLS version and cipher constraints
| +| [`HTTPRoute`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.HTTPRoute) |
  • Weight-based load balancing
  • Supported rules: path, header, query, and method-based matching
  • Supported filters: header addition, removal, and setting
  • Supported backend types:
    1. `core/v1/Service` (must map to a registered Consul service)
    2. `api-gateway.consul.hashicorp.com/v1alpha1/MeshService`
| +| [`TCPRoute`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.TCPRoute) |
  • Supported backend types:
    1. `core/v1/Service` (must map to a registered Consul service)
    2. `api-gateway.consul.hashicorp.com/v1alpha1/MeshService`
| \ No newline at end of file From be6528e80bcf63124b1c27b9a1f06b2ff67cfceb Mon Sep 17 00:00:00 2001 From: Andrew Stucki Date: Wed, 23 Feb 2022 11:45:21 -0500 Subject: [PATCH 27/40] Update website/content/docs/api-gateway/kubernetes-features.mdx Co-authored-by: Jeff-Apple <79924108+Jeff-Apple@users.noreply.github.com> --- website/content/docs/api-gateway/kubernetes-features.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/content/docs/api-gateway/kubernetes-features.mdx b/website/content/docs/api-gateway/kubernetes-features.mdx index 10e66f9619..bd0482a5e3 100644 --- a/website/content/docs/api-gateway/kubernetes-features.mdx +++ b/website/content/docs/api-gateway/kubernetes-features.mdx @@ -5,9 +5,9 @@ description: >- Consul API Gateway Supported Kubernetes Features. --- -# Consul API Gateway - Gateway Spec Features +# Consul API Gateway - Kubernetes Gateway Spec Features -The Consul API Gateway currently supports a subset of the [v1alpha2 Gateway API Spec](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/). The table below +The Consul API Gateway currently supports a subset of the Kubernetes [v1alpha2 Gateway API Spec](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/). The table below specifies the supported features of the spec. For a full list of features, including the list of gateway and route statuses and an explanation on how they are used, see the [in-repo documentation](https://github.com/hashicorp/consul-api-gateway/blob/main/dev/docs/supported-features.md). From 4d17e106922682f2bd17e800f1f66ede1228ba18 Mon Sep 17 00:00:00 2001 From: Andrew Stucki Date: Wed, 23 Feb 2022 11:45:29 -0500 Subject: [PATCH 28/40] Update website/content/docs/api-gateway/kubernetes-features.mdx Co-authored-by: Jeff-Apple <79924108+Jeff-Apple@users.noreply.github.com> --- website/content/docs/api-gateway/kubernetes-features.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/kubernetes-features.mdx b/website/content/docs/api-gateway/kubernetes-features.mdx index bd0482a5e3..dbffc048e5 100644 --- a/website/content/docs/api-gateway/kubernetes-features.mdx +++ b/website/content/docs/api-gateway/kubernetes-features.mdx @@ -9,7 +9,7 @@ description: >- The Consul API Gateway currently supports a subset of the Kubernetes [v1alpha2 Gateway API Spec](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/). The table below specifies the supported features of the spec. For a full list of features, including the list of gateway and route statuses and an explanation on how they -are used, see the [in-repo documentation](https://github.com/hashicorp/consul-api-gateway/blob/main/dev/docs/supported-features.md). +are used, see the [documentation in our GitHub repo](https://github.com/hashicorp/consul-api-gateway/blob/main/dev/docs/supported-features.md). | Kubernetes Object | Features | | ----- | ----------------------------- | From e0980b5bddf1c68484904058af1005f90b4f4aed Mon Sep 17 00:00:00 2001 From: Mike Morris Date: Wed, 23 Feb 2022 12:26:49 -0500 Subject: [PATCH 29/40] Update website/content/docs/api-gateway/index.mdx Co-authored-by: Andrew Stucki --- website/content/docs/api-gateway/index.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/content/docs/api-gateway/index.mdx b/website/content/docs/api-gateway/index.mdx index d037e48ec7..4a56ffee1c 100644 --- a/website/content/docs/api-gateway/index.mdx +++ b/website/content/docs/api-gateway/index.mdx @@ -186,8 +186,8 @@ The following table describes the allowed parameters for the `spec` array: | `consul.ports.http` | Specifies the port for Consul's HTTP server. | Integer | `8500` | | `consul.scheme` | Specifies the scheme to use for connecting to Consul. The supported values are `"http"` and `"https"`. | String | `"http"` | | `copyAnnotations.service` | List of annotations to copy to the gateway service. | Array | `["external-dns.alpha.kubernetes.io/hostname"]` | -| `image.consulAPIGateway` | The image to use for consul-api-gateway. View available image tags on [DockerHub](https://hub.docker.com/r/hashicorp/consul-api-gateway/tags). | String | `"hashicorp/consul-api-gateway:RELEASE_VERSION"` | -| `image.envoy` | Specifies the container image to use for Envoy. View available image tags on [DockerHub](https://hub.docker.com/r/envoyproxy/envoy/tags). | String | `"envoyproxy/envoy:RELEASE_VERSION"` | +| `image.consulAPIGateway` | The image to use for consul-api-gateway. View available image tags on [DockerHub](https://hub.docker.com/r/hashicorp/consul-api-gateway/tags). | String | `"hashicorp/consul-api-gateway:0.1.0"` | +| `image.envoy` | Specifies the container image to use for Envoy. View available image tags on [DockerHub](https://hub.docker.com/r/envoyproxy/envoy/tags). | String | `"envoyproxy/envoy:v1.20-latest"` | | `logLevel` | Specifies the error reporting level for logs. You can specify the following values: `error`, `warning`, `info`, `debug`, `trace`. | String | `"info"` | | `nodeSelector` | Specifies a set of parameters that constrain the nodes on which the pod can run. Defining nodes with the `nodeSelector` enables the pod to fit on a node. The selector must match a node's labels for the pod to be scheduled on that node. Refer to the [Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/) for additional information. | Object | N/A | | `serviceType` | Specifies the ingress methods for a service. The following values are supported:
`ClusterIP`
`NodePort`
`LoadBalancer`. | String | N/A | From 94a7963de74fd2940ab9784a81e473a1ed5962d8 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Wed, 23 Feb 2022 09:42:24 -0800 Subject: [PATCH 30/40] merged the k8s features section into the overview --- website/content/docs/api-gateway/index.mdx | 13 +++++++++++++ .../docs/api-gateway/kubernetes-features.mdx | 19 ------------------- website/data/docs-nav-data.json | 4 ---- 3 files changed, 13 insertions(+), 23 deletions(-) delete mode 100644 website/content/docs/api-gateway/kubernetes-features.mdx diff --git a/website/content/docs/api-gateway/index.mdx b/website/content/docs/api-gateway/index.mdx index f433ea6515..29d1d3a54f 100644 --- a/website/content/docs/api-gateway/index.mdx +++ b/website/content/docs/api-gateway/index.mdx @@ -22,6 +22,19 @@ Consul API Gateway solves the following primary use cases: Consul API Gateway implements the Kubernetes [Gateway API Specification](https://gateway-api.sigs.k8s.io/). This specification defines a set of custom resource definitions (CRD) that can create logical gateways and routes based on the path or protocol of a client request. +### Supported Kubernetes Gateway Specification Features + +The Consul API Gateway supports a subset of the Kubernetes [v1alpha2 Gateway API specification](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/). The following table +describes the supported features of the specification. For a complete list of features, including the list of gateway and route statuses and an explanation on how they +are used, see the [documentation in our GitHub repo](https://github.com/hashicorp/consul-api-gateway/blob/main/dev/docs/supported-features.md). + +| Kubernetes Object | Description | +| ----- | ----------------------------- | +| [`GatewayClass`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.GatewayClass) |
  • Parameter specification via `GatewayClassConfig` CRD
  • Controller matching on `"hashicorp.com/consul-api-gateway-controller"`
| +| [`Gateway`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.Gateway) |
  • Supported protocols: `HTTP`, `HTTPS`, `TCP`
  • Header-based hostname matching (no SNI support)
  • Supported filters: header addition, removal, and setting
  • TLS modes supported: `terminate`
  • Certificate types supported: `core/v1/Secret`
  • Extended options: TLS version and cipher constraints
| +| [`HTTPRoute`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.HTTPRoute) |
  • Weight-based load balancing
  • Supported rules: path, header, query, and method-based matching
  • Supported filters: header addition, removal, and setting
  • Supported backend types:
    1. `core/v1/Service` (must map to a registered Consul service)
    2. `api-gateway.consul.hashicorp.com/v1alpha1/MeshService`
| +| [`TCPRoute`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.TCPRoute) |
  • Supported backend types:
    1. `core/v1/Service` (must map to a registered Consul service)
    2. `api-gateway.consul.hashicorp.com/v1alpha1/MeshService`
| + ## Additional Resources You can learn more about using Consul API Gateway by completing the [Consul API Gateway tutorial](https://learn.hashicorp.com/tutorials/consul/kubernetes-api-gateway). diff --git a/website/content/docs/api-gateway/kubernetes-features.mdx b/website/content/docs/api-gateway/kubernetes-features.mdx deleted file mode 100644 index dbffc048e5..0000000000 --- a/website/content/docs/api-gateway/kubernetes-features.mdx +++ /dev/null @@ -1,19 +0,0 @@ ---- -layout: docs -page_title: Consul API Gateway Supported Kubernetes Features -description: >- - Consul API Gateway Supported Kubernetes Features. ---- - -# Consul API Gateway - Kubernetes Gateway Spec Features - -The Consul API Gateway currently supports a subset of the Kubernetes [v1alpha2 Gateway API Spec](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/). The table below -specifies the supported features of the spec. For a full list of features, including the list of gateway and route statuses and an explanation on how they -are used, see the [documentation in our GitHub repo](https://github.com/hashicorp/consul-api-gateway/blob/main/dev/docs/supported-features.md). - -| Kubernetes Object | Features | -| ----- | ----------------------------- | -| [`GatewayClass`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.GatewayClass) |
  • Parameter specification via `GatewayClassConfig` CRD
  • Controller matching on `"hashicorp.com/consul-api-gateway-controller"`
| -| [`Gateway`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.Gateway) |
  • Supported protocols: `HTTP`, `HTTPS`, `TCP`
  • Header-based hostname matching (no SNI support)
  • Supported filters: header addition, removal, and setting
  • TLS modes supported: `terminate`
  • Certificate types supported: `core/v1/Secret`
  • Extended options: TLS version and cipher constraints
| -| [`HTTPRoute`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.HTTPRoute) |
  • Weight-based load balancing
  • Supported rules: path, header, query, and method-based matching
  • Supported filters: header addition, removal, and setting
  • Supported backend types:
    1. `core/v1/Service` (must map to a registered Consul service)
    2. `api-gateway.consul.hashicorp.com/v1alpha1/MeshService`
| -| [`TCPRoute`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.TCPRoute) |
  • Supported backend types:
    1. `core/v1/Service` (must map to a registered Consul service)
    2. `api-gateway.consul.hashicorp.com/v1alpha1/MeshService`
| \ No newline at end of file diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index be4e142370..0130d1f472 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -388,10 +388,6 @@ { "title": "Technical Specifications", "path": "api-gateway/tech-specs" - }, - { - "title": "Supported Kubernetes Features", - "path": "api-gateway/kubernetes-features" } ] }, From cc00e5e403db9892993b07f925c333e067415bf3 Mon Sep 17 00:00:00 2001 From: Jeff-Apple <79924108+Jeff-Apple@users.noreply.github.com> Date: Thu, 24 Feb 2022 07:25:58 -0800 Subject: [PATCH 31/40] Minor edits and additions to the API Gateway docs. --- website/content/docs/api-gateway/api-gateway-usage.mdx | 2 +- website/content/docs/api-gateway/index.mdx | 6 +++++- website/content/docs/api-gateway/tech-specs.mdx | 1 + 3 files changed, 7 insertions(+), 2 deletions(-) diff --git a/website/content/docs/api-gateway/api-gateway-usage.mdx b/website/content/docs/api-gateway/api-gateway-usage.mdx index d901c2540c..1802fc347a 100644 --- a/website/content/docs/api-gateway/api-gateway-usage.mdx +++ b/website/content/docs/api-gateway/api-gateway-usage.mdx @@ -25,7 +25,7 @@ Refer to [Technical Specifications](/docs/api-gateway/tech-specs) for minimum so -1. Create a `values.yaml` file for your Consul API Gateway deployment. Copy the content below into the `values.yaml` file. The `values.yaml` will be used by the Consul Helm chart. See [Helm Chart Configuration - apigateway](https://www.consul.io/docs/k8s/helm#apigateway) for more available options on how to configure your Consul API Gateway deployment via the Helm chart. +1. Create a `values.yaml` file for your Consul API Gateway deployment. Copy the content below into the `values.yaml` file. The `values.yaml` will be used by the Consul Helm chart. See [Helm Chart Configuration - apiGateway](https://www.consul.io/docs/k8s/helm#apigateway) for more available options on how to configure your Consul API Gateway deployment via the Helm chart. diff --git a/website/content/docs/api-gateway/index.mdx b/website/content/docs/api-gateway/index.mdx index 29d1d3a54f..c8ee5a2402 100644 --- a/website/content/docs/api-gateway/index.mdx +++ b/website/content/docs/api-gateway/index.mdx @@ -20,7 +20,11 @@ Consul API Gateway solves the following primary use cases: ## Implementation -Consul API Gateway implements the Kubernetes [Gateway API Specification](https://gateway-api.sigs.k8s.io/). This specification defines a set of custom resource definitions (CRD) that can create logical gateways and routes based on the path or protocol of a client request. +Consul API Gateway can be deoployed, currently, only on Kubernetes-based runtime environments. Addional runtimes will be supported In the future. It also requires Consul Service Mesh be deployed on the Kubernetes cluster. + +API Gateway can route traffic to services connected to the same service mesh its connected to. Those services can be running on the Kubernetes cluster or somewhere else, if they are connected to the same service mesh. + +Consul API Gateway implements, and is configured through, the Kubernetes [Gateway API Specification](https://gateway-api.sigs.k8s.io/). This specification defines a set of custom resource definitions (CRD) that can create logical gateways and routes based on the path or protocol of a client request. ### Supported Kubernetes Gateway Specification Features diff --git a/website/content/docs/api-gateway/tech-specs.mdx b/website/content/docs/api-gateway/tech-specs.mdx index eb5639dd28..9182323e89 100644 --- a/website/content/docs/api-gateway/tech-specs.mdx +++ b/website/content/docs/api-gateway/tech-specs.mdx @@ -21,6 +21,7 @@ Your datacenter must meet the following requirements prior to configuring the Co - `kubectl` 1.21+ - Consul 1.11.2+ - HashiCorp Consul Helm chart 0.41.0+ +- Consul Service Mesh must be deployed on the Kubernetes cluster that API Gateway is deployed on. ### TCP Port Requirements From 871625e3213b62e9b6c68f2d4d5b4fff663f8b2f Mon Sep 17 00:00:00 2001 From: Nathan Coleman Date: Thu, 24 Feb 2022 12:51:55 -0500 Subject: [PATCH 32/40] Update website/content/docs/api-gateway/api-gateway-usage.mdx Co-authored-by: Andrew Stucki --- website/content/docs/api-gateway/api-gateway-usage.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/api-gateway-usage.mdx b/website/content/docs/api-gateway/api-gateway-usage.mdx index 1802fc347a..29a8ba31d5 100644 --- a/website/content/docs/api-gateway/api-gateway-usage.mdx +++ b/website/content/docs/api-gateway/api-gateway-usage.mdx @@ -49,7 +49,7 @@ Refer to [Technical Specifications](/docs/api-gateway/tech-specs) for minimum so ```shell-session - $ helm install consul hashicorp/consul --version 0.41.0 --values values.yaml + $ helm install consul hashicorp/consul --version 0.41.1 --values values.yaml ``` From dc873138df6c27ea3a2b84dfb24ef7f9b57217f5 Mon Sep 17 00:00:00 2001 From: Nathan Coleman Date: Thu, 24 Feb 2022 12:52:03 -0500 Subject: [PATCH 33/40] Update website/content/docs/api-gateway/tech-specs.mdx Co-authored-by: Andrew Stucki --- website/content/docs/api-gateway/tech-specs.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/tech-specs.mdx b/website/content/docs/api-gateway/tech-specs.mdx index 9182323e89..20ff2a1f8d 100644 --- a/website/content/docs/api-gateway/tech-specs.mdx +++ b/website/content/docs/api-gateway/tech-specs.mdx @@ -20,7 +20,7 @@ Your datacenter must meet the following requirements prior to configuring the Co - Kubernetes 1.21+ - `kubectl` 1.21+ - Consul 1.11.2+ -- HashiCorp Consul Helm chart 0.41.0+ +- HashiCorp Consul Helm chart 0.41.1+ - Consul Service Mesh must be deployed on the Kubernetes cluster that API Gateway is deployed on. ### TCP Port Requirements From 5bc1e75e8f9866081f9b7c13db10a114a58b26d0 Mon Sep 17 00:00:00 2001 From: Jeff-Apple <79924108+Jeff-Apple@users.noreply.github.com> Date: Thu, 24 Feb 2022 09:56:55 -0800 Subject: [PATCH 34/40] Updated helm chart version number and a minor edit --- website/content/docs/api-gateway/api-gateway-usage.mdx | 6 ++++-- website/content/docs/api-gateway/tech-specs.mdx | 2 +- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/website/content/docs/api-gateway/api-gateway-usage.mdx b/website/content/docs/api-gateway/api-gateway-usage.mdx index 1802fc347a..90e0d008bb 100644 --- a/website/content/docs/api-gateway/api-gateway-usage.mdx +++ b/website/content/docs/api-gateway/api-gateway-usage.mdx @@ -32,7 +32,7 @@ Refer to [Technical Specifications](/docs/api-gateway/tech-specs) for minimum so ```yaml global: name: consul - image: 'hashicorp/consul:1.11.2' + image: 'hashicorp/consul:1.11.3' connectInject: enabled: true controller: @@ -49,7 +49,7 @@ Refer to [Technical Specifications](/docs/api-gateway/tech-specs) for minimum so ```shell-session - $ helm install consul hashicorp/consul --version 0.41.0 --values values.yaml + $ helm install consul hashicorp/consul --version 0.41.1 --values values.yaml ``` @@ -138,6 +138,8 @@ Configure the following artifacts to facilitate ingress into your Consul service - [Gateway](#gateway): Defines the main infrastructure resource that links API gateway components. It specifies the name of the `GatewayClass` and one or more `listeners` (see [Listeners](#listeners)), which specify the logical endpoints bound to the gateway's addresses. - [Routes](#routes): Specifies the path from the client to the listener. +-> ** Note:** If `managedGatewayClass` is enabled in the Helm chart, a `GatewayClassConfig` and `GatewayClass` will be created automatically and should be configured via [Helm chart options](https://www.consul.io/docs/k8s/helm#v-apigateway-managedgatewayclass) instead of this custom resource. + ### GatewayClassConfig The `GatewayClassConfig` object describes Consul API Gateway-related configuration parameters for the [`GatewayClass`](#gatewayclass). diff --git a/website/content/docs/api-gateway/tech-specs.mdx b/website/content/docs/api-gateway/tech-specs.mdx index 9182323e89..20ff2a1f8d 100644 --- a/website/content/docs/api-gateway/tech-specs.mdx +++ b/website/content/docs/api-gateway/tech-specs.mdx @@ -20,7 +20,7 @@ Your datacenter must meet the following requirements prior to configuring the Co - Kubernetes 1.21+ - `kubectl` 1.21+ - Consul 1.11.2+ -- HashiCorp Consul Helm chart 0.41.0+ +- HashiCorp Consul Helm chart 0.41.1+ - Consul Service Mesh must be deployed on the Kubernetes cluster that API Gateway is deployed on. ### TCP Port Requirements From ba36bdc2e5542430132c8b1a9d4bf2af066f6472 Mon Sep 17 00:00:00 2001 From: Jeff-Apple <79924108+Jeff-Apple@users.noreply.github.com> Date: Thu, 24 Feb 2022 12:14:06 -0800 Subject: [PATCH 35/40] Update website/content/docs/api-gateway/api-gateway-usage.mdx Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> --- website/content/docs/api-gateway/api-gateway-usage.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/api-gateway-usage.mdx b/website/content/docs/api-gateway/api-gateway-usage.mdx index 90e0d008bb..6b0da10731 100644 --- a/website/content/docs/api-gateway/api-gateway-usage.mdx +++ b/website/content/docs/api-gateway/api-gateway-usage.mdx @@ -58,7 +58,7 @@ Refer to [Technical Specifications](/docs/api-gateway/tech-specs) for minimum so 1. Verify that the [requirements](#requirements) have been met. 1. Verify that the Consul API Gateway CRDs and controller have been installed and applied (see [Installation](#installation)). -1. Configure the artifacts described below in [Configuration](#configuration). If the following config is added to the `values.yaml` Helm config, the GatewayClassConfig and GatewayClass will be created automatically, and only the Gateway, Listeners and Routes will need to be configured manually. The [`serviceType`](https://www.consul.io/docs/k8s/helm#v-apigateway-managedgatewayclass-servicetype) for a managed GatewayClass will default to `LoadBalancer`, which is appropriate for most deployments to managed Kubernetes cloud offerings (EKS, GKE, AKS) - other deployments, such as to a [kind](https://kind.sigs.k8s.io/) cluster, may require specifying `NodePort` or `ClusterIP` instead. +1. Configure the artifacts described below in [Configuration](#configuration). From f56981baf58be29d097262f3f6c4a67c08d61c3a Mon Sep 17 00:00:00 2001 From: Jeff-Apple <79924108+Jeff-Apple@users.noreply.github.com> Date: Thu, 24 Feb 2022 12:16:47 -0800 Subject: [PATCH 36/40] Update website/content/docs/api-gateway/api-gateway-usage.mdx Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> --- website/content/docs/api-gateway/api-gateway-usage.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/api-gateway-usage.mdx b/website/content/docs/api-gateway/api-gateway-usage.mdx index 6b0da10731..29a239c3ca 100644 --- a/website/content/docs/api-gateway/api-gateway-usage.mdx +++ b/website/content/docs/api-gateway/api-gateway-usage.mdx @@ -145,7 +145,7 @@ Configure the following artifacts to facilitate ingress into your Consul service The `GatewayClassConfig` object describes Consul API Gateway-related configuration parameters for the [`GatewayClass`](#gatewayclass). Add the `kind: GatewayClassConfig` option to the gateway values file to declare a gateway class. -The following example creates a gateway class config called `test-gateway-class-config`: +The following example creates a gateway class configuration called `test-gateway-class-config`: From 7e515eef97ec3cd079ced487676417ff3e42e8ba Mon Sep 17 00:00:00 2001 From: Jeff-Apple <79924108+Jeff-Apple@users.noreply.github.com> Date: Thu, 24 Feb 2022 12:20:32 -0800 Subject: [PATCH 37/40] Update website/content/docs/api-gateway/index.mdx Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> --- website/content/docs/api-gateway/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/index.mdx b/website/content/docs/api-gateway/index.mdx index c8ee5a2402..66e31acb59 100644 --- a/website/content/docs/api-gateway/index.mdx +++ b/website/content/docs/api-gateway/index.mdx @@ -20,7 +20,7 @@ Consul API Gateway solves the following primary use cases: ## Implementation -Consul API Gateway can be deoployed, currently, only on Kubernetes-based runtime environments. Addional runtimes will be supported In the future. It also requires Consul Service Mesh be deployed on the Kubernetes cluster. +Consul API Gateway can be deployed on Kubernetes-based runtime environments and requires that Consul service mesh be deployed on the Kubernetes cluster. API Gateway can route traffic to services connected to the same service mesh its connected to. Those services can be running on the Kubernetes cluster or somewhere else, if they are connected to the same service mesh. From 6f80f9c4a7af384517af17f3295575994130ff53 Mon Sep 17 00:00:00 2001 From: Jeff-Apple <79924108+Jeff-Apple@users.noreply.github.com> Date: Thu, 24 Feb 2022 12:21:04 -0800 Subject: [PATCH 38/40] Update website/content/docs/api-gateway/api-gateway-usage.mdx Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> --- website/content/docs/api-gateway/api-gateway-usage.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/api-gateway-usage.mdx b/website/content/docs/api-gateway/api-gateway-usage.mdx index 29a239c3ca..3349f763d2 100644 --- a/website/content/docs/api-gateway/api-gateway-usage.mdx +++ b/website/content/docs/api-gateway/api-gateway-usage.mdx @@ -138,7 +138,7 @@ Configure the following artifacts to facilitate ingress into your Consul service - [Gateway](#gateway): Defines the main infrastructure resource that links API gateway components. It specifies the name of the `GatewayClass` and one or more `listeners` (see [Listeners](#listeners)), which specify the logical endpoints bound to the gateway's addresses. - [Routes](#routes): Specifies the path from the client to the listener. --> ** Note:** If `managedGatewayClass` is enabled in the Helm chart, a `GatewayClassConfig` and `GatewayClass` will be created automatically and should be configured via [Helm chart options](https://www.consul.io/docs/k8s/helm#v-apigateway-managedgatewayclass) instead of this custom resource. +-> ** Note:** Add the following `managedGatewayClass` configuration to the `values.yaml` Helm configuration to enable the `GatewayClassConfig` and `GatewayClass` to be created automatically. The gateway, listeners, and routes will need to be configured manually. When `managedGatewayClass` is enabled, the [`serviceType`](/docs/k8s/helm#v-apigateway-managedgatewayclass-servicetype) for a managed `GatewayClass` will also default to `LoadBalancer`, which is appropriate for most deployments to managed Kubernetes cloud offerings (i.e., EKS, GKE, AKS). Other deployments, such as to a [kind](https://kind.sigs.k8s.io/) cluster, may require specifying `NodePort` or `ClusterIP`, instead. ### GatewayClassConfig From 31e6ec62f0f63c8c5f4d5eebb893b16e79622060 Mon Sep 17 00:00:00 2001 From: Jeff-Apple <79924108+Jeff-Apple@users.noreply.github.com> Date: Thu, 24 Feb 2022 12:23:51 -0800 Subject: [PATCH 39/40] Update website/content/docs/api-gateway/api-gateway-usage.mdx Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> --- website/content/docs/api-gateway/api-gateway-usage.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/api-gateway-usage.mdx b/website/content/docs/api-gateway/api-gateway-usage.mdx index 3349f763d2..04f8daf5a1 100644 --- a/website/content/docs/api-gateway/api-gateway-usage.mdx +++ b/website/content/docs/api-gateway/api-gateway-usage.mdx @@ -308,7 +308,7 @@ spec: ### MeshService -MeshService holds a reference to an externally managed Consul Service Mesh service, and can be used as a `backendRef` for a [`Route`](#route). +The `MeshService` configuration holds a reference to an externally-managed Consul service mesh service and can be used as a `backendRef` for a [`Route`](#route). | Parameter | Description | Type | Default | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------- | From eea07af17a1f134442896d2552513898e94e537c Mon Sep 17 00:00:00 2001 From: Jeff-Apple <79924108+Jeff-Apple@users.noreply.github.com> Date: Thu, 24 Feb 2022 12:27:17 -0800 Subject: [PATCH 40/40] Update website/content/docs/api-gateway/index.mdx Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> --- website/content/docs/api-gateway/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/index.mdx b/website/content/docs/api-gateway/index.mdx index 66e31acb59..817aa823ec 100644 --- a/website/content/docs/api-gateway/index.mdx +++ b/website/content/docs/api-gateway/index.mdx @@ -22,7 +22,7 @@ Consul API Gateway solves the following primary use cases: Consul API Gateway can be deployed on Kubernetes-based runtime environments and requires that Consul service mesh be deployed on the Kubernetes cluster. -API Gateway can route traffic to services connected to the same service mesh its connected to. Those services can be running on the Kubernetes cluster or somewhere else, if they are connected to the same service mesh. +API Gateway routes traffic to services connected to the same service mesh. Those services can be running on the same Kubernetes cluster as the API Gateway, a different Kubernetes cluster, or another runtime, as long as they are connected to the same service mesh deployment and reachable over the network. Consul API Gateway implements, and is configured through, the Kubernetes [Gateway API Specification](https://gateway-api.sigs.k8s.io/). This specification defines a set of custom resource definitions (CRD) that can create logical gateways and routes based on the path or protocol of a client request.