From f36d18c469f36e346cd332b08d7c2530bd27aaa1 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 000000000..a57e5cfb4 --- /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 7c1c096b9..62a0a0f59 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 5138a9987..5bee60376 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 7d88a36e8c0e59930270510ba7f2cf7d8e72cc2d 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 62a0a0f59..f552a9bab 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 3b80823eebc69ac0d8fafc24c4005116fea922e4 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 f552a9bab..3fe7a4692 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 054520cd02805077fb5556652e7c0ff821f62f37 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 6d9f600d5..b37010b97 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 ee44ae7d519fb0d2d80cdb07846ace453fbab424 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 3fe7a4692..07c256279 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 8fbc98576bfa4a4d8f7eb44a1638607b73cdcbf4 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 b37010b97..6d9f600d5 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 727c099b46c0a4ddbe883fbc414ec578b81126f2 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 07c256279..4482d352d 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 d28e62c18139c7f091a26806990ac426ae55f922 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 4482d352d..c3ef0cc8f 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 fba0d8f14b86c5ac770da9dbb43ec398b3d29c31 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 c3ef0cc8f..d97715204 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 978aeab38c398c146d65d790170c43d3836c7ec6 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 d97715204..a28d410e4 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 5308c3e9219772b545bdbc9cbc0541f1a4448cd0 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 a28d410e4..126defe0c 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 13b1fe0743ced84da8efa70a89c24b511e02a438 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 126defe0c..a780b1971 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 345a19e3612d4e8bfa9ac903d32c03e7e8397af3 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 a780b1971..a7dea1b49 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 d57248281993174a0693292182673b5d746ae12a 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 a7dea1b49..616f18097 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 68ce10c36347edf97ec02a12cedfb555354e7632 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 616f18097..7ab4b9749 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 ef70dc80cfd9b90956b266e9a30c13cc06eca23d 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 7ab4b9749..5edad13fd 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 dd9952ae2c7e4bfc00cd97cfcc2f7f50f1ee1bb4 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 a57e5cfb4..c63abd3ee 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 7725ee0cb646540dfa914ec617648ee83200fda3 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 c63abd3ee..0cd0f5ff4 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 877a556fba713db0ae505b45836f2d60546d851b 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 0cd0f5ff4..12245b184 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 5edad13fd..3c84c8b59 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 e45e55f5f8af8399975d945b2a8040b2c3f3098f 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 3c84c8b59..d037e48ec 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 d3eb57ad9dcbb4b3bf0330b6513e268612a9d524 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 5bee60376..51077a327 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 c0e6953eab0cf7942f104fdf89fe792b6f9be3fa 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 12245b184..c9d0a617f 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 c57ab13f7d6e7289c9ef8ef782eab5222e5d6b10 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 d037e48ec..f433ea651 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 12245b184..eb5639dd2 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 51077a327..0130d1f47 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 1693d032bbddfde96414dab8f8051a168a2d2feb 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 000000000..d901c2540 --- /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 70dabc551fb80e882490986c1a19ccf4674b32c9 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 000000000..5a6ac5238 --- /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 51077a327..a18c3be90 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 6fcf2cbb7d01dbc8cbe509271885cec8452b0176 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 5a6ac5238..10e66f961 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 45f8c560a1976c007f08fd3ac2c9268c57579b79 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 10e66f961..bd0482a5e 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 6351495c65cc849356236d565daecb561e618ecd 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 bd0482a5e..dbffc048e 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 bca9f4a088564dd7c39e2880a48c8a15005298d0 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 d037e48ec..4a56ffee1 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 dd89b6ba9b0255862cc3e180e2b215f8a58e8424 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 f433ea651..29d1d3a54 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 dbffc048e..000000000 --- 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 be4e14237..0130d1f47 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 6e303294c4316a83c548ca7336ed1634ab4c9410 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 d901c2540..1802fc347 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 29d1d3a54..c8ee5a240 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 eb5639dd2..9182323e8 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 bc4b3ce87d3740b437851fe5869ec066d3d041dc 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 1802fc347..29a8ba31d 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 74bffe4cf73a40eb82084f3275e466fee3cbe369 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 9182323e8..20ff2a1f8 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 e8788c528de757f50d436db46de66b634034a822 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 1802fc347..90e0d008b 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 9182323e8..20ff2a1f8 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 0095046c69d8c2395201bce3ffd31977fccc76d6 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 90e0d008b..6b0da1073 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 815599b06cf57ca84d2433e04ab628aecbdc6766 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 6b0da1073..29a239c3c 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 46a9ee9f47fb364da07626e8465ecbf4735c5a42 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 c8ee5a240..66e31acb5 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 bf13b0504fa46f1f2c79e7135cc8ef0c18f2d4e2 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 29a239c3c..3349f763d 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 605b0ebc73bbc17dee81155eb56266ce5b148b12 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 3349f763d..04f8daf5a 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 7f2d35a15b1ce5e09c3a3d50923e0b63d17e77b7 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 66e31acb5..817aa823e 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.