From 484bb5c59d437fe78fd504791ec87244164ead12 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Tue, 22 Feb 2022 16:44:30 -0800 Subject: [PATCH] separated overview content and usage content into their own pages --- website/content/docs/api-gateway/index.mdx | 316 +----------------- .../content/docs/api-gateway/tech-specs.mdx | 50 ++- website/data/docs-nav-data.json | 4 + 3 files changed, 36 insertions(+), 334 deletions(-) diff --git a/website/content/docs/api-gateway/index.mdx b/website/content/docs/api-gateway/index.mdx index d037e48ec7..f433ea6515 100644 --- a/website/content/docs/api-gateway/index.mdx +++ b/website/content/docs/api-gateway/index.mdx @@ -1,324 +1,28 @@ --- layout: docs -page_title: API Gateway +page_title: Consul API Gateway Overview description: >- Using Consul API gateway functionality --- -# Consul API Gateway +# Consul API Gateway Overview -This topic describes how to use the Consul API Gateway add-on module, which helps users control access to services running within a Consul service mesh. The API gateway enables external network clients to access applications and services running in a Consul datacenter. This type of network traffic is commonly referred to as "north-south" network traffic as it refers to the flow of data into and out of a specific environment. Requests from clients can also be forwarded based on path or request protocol. +This topic provides an overview of the Consul API Gateway. -You can learn more about using Consul API Gateway by completing the [Consul API Gateway tutorial](https://learn.hashicorp.com/tutorials/consul/kubernetes-api-gateway). +## What is Consul API Gateway? -## Introduction +Consul API Gateway is an add-on for Consul that helps users control access to services running within a Consul service mesh. The API gateway enables external network clients to access applications and services running in a Consul datacenter. This type of network traffic is commonly referred to as "north-south" network traffic as it refers to the flow of data into and out of a specific environment. Requests from clients can also be forwarded based on path or request protocol. -Consul API Gateway implements the Kubernetes [Gateway API Specification](https://gateway-api.sigs.k8s.io/). This specification defines a set of custom resource definitions (CRD) that can create logical gateways and routes based on the path or protocol of a client request. Consul API Gateway solves two primary use cases: +Consul API Gateway solves the following primary use cases: - **Controlling access at the point of entry**: Consul API Gateway allows users to set the protocols of external connection requests and provide clients with TLS certificates from trusted providers (e.g., Verisign, Let’s Encrypt). - **Simplifying traffic management**: The Consul API Gateway can load balance requests across services and route traffic to the appropriate service by matching one or more criteria, such as hostname, path, header presence or value, and HTTP Method type (e.g., GET, POST, PATCH). -## Requirements +## Implementation -Refer to the [Technical Specifications](/docs/api-gateway/tech-specs) page for minimum software requirements. +Consul API Gateway implements the Kubernetes [Gateway API Specification](https://gateway-api.sigs.k8s.io/). This specification defines a set of custom resource definitions (CRD) that can create logical gateways and routes based on the path or protocol of a client request. -## Installation +## Additional Resources -1. Issue the following command to install the CRDs: +You can learn more about using Consul API Gateway by completing the [Consul API Gateway tutorial](https://learn.hashicorp.com/tutorials/consul/kubernetes-api-gateway). - - - ```shell-session - $ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?ref=v0.1.0" - ``` - - - -1. Create a `values.yaml` file for your Consul API Gateway deployment. Copy the content below into the `values.yaml` file. The `values.yaml` will be used by the Consul Helm chart. See [Helm Chart Configuration - apigateway](https://www.consul.io/docs/k8s/helm#apigateway) for more available options on how to configure your Consul API Gateway deployment via the Helm chart. - - - - ```yaml - global: - name: consul - image: 'hashicorp/consul:1.11.2' - connectInject: - enabled: true - controller: - enabled: true - apiGateway: - enabled: true - image: hashicorp/consul-api-gateway:0.1.0 - ``` - - - -1. Install Consul API Gateway using the standard Consul Helm chart and specify the custom values file. - - - - ```shell-session - $ helm install consul hashicorp/consul --version 0.41.0 --values values.yaml - ``` - - - -## Usage - -1. Verify that the [requirements](#requirements) have been met. -1. Verify that the Consul API Gateway CRDs and controller have been installed and applied (see [Installation](#installation)). -1. Configure the artifacts described below in [Configuration](#configuration). If the following config is added to the `values.yaml` Helm config, the GatewayClassConfig and GatewayClass will be created automatically, and only the Gateway, Listeners and Routes will need to be configured manually. The [`serviceType`](https://www.consul.io/docs/k8s/helm#v-apigateway-managedgatewayclass-servicetype) for a managed GatewayClass will default to `LoadBalancer`, which is appropriate for most deployments to managed Kubernetes cloud offerings (EKS, GKE, AKS) - other deployments, such as to a [kind](https://kind.sigs.k8s.io/) cluster, may require specifying `NodePort` or `ClusterIP` instead. - - - - ```yaml - apiGateway: - managedGatewayClass: - enabled: true - ``` - - - -1. Issue the `kubectl apply` command to implement the configurations, e.g.: - - - - ```shell-session - $ kubectl apply -f gateway.yaml routes.yaml - ``` - - - - - -## Configuration - -Configure the following artifacts to facilitate ingress into your Consul service mesh: - -- [GatewayClassConfig](#gatewayclassconfig): Describes additional Consul API Gateway-related configuration parameters for the `GatewayClass` resource. -- [GatewayClass](#gatewayclass): Defines a class of gateway resources that you can use as a template for creating gateways. -- [Gateway](#gateway): Defines the main infrastructure resource that links API gateway components. It specifies the name of the `GatewayClass` and one or more `listeners` (see [Listeners](#listeners)), which specify the logical endpoints bound to the gateway's addresses. -- [Routes](#routes): Specifies the path from the client to the listener. - -### GatewayClassConfig - -The `GatewayClassConfig` object describes Consul API Gateway-related configuration parameters for the [`GatewayClass`](#gatewayclass). - -Add the `kind: GatewayClassConfig` option to the gateway values file to declare a gateway class. -The following example creates a gateway class config called `test-gateway-class-config`: - - - -```yaml -apiVersion: api-gateway.consul.hashicorp.com/v1alpha1 -kind: GatewayClassConfig -metadata: - name: test-gateway-class-config -spec: - useHostPorts: true - logLevel: 'trace' - consul: - scheme: 'https' - ports: - http: 8501 - grpc: 8502 -``` - - - -The following table describes the allowed parameters for the `spec` array: - -| Parameter | Description | Type | Default | -| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------ | -| `consul.address` | Specifies the address of the Consul server to communicate with in the gateway pod. If unspecified, the pod will attempt to use a local agent on the host on which the pod is running. | String | N/A | -| `consul.authentication.account` | Specifies the Kubernetes service account to use for authentication. | String | N/A | -| `consul.authentication.managed` | Set to `true` to enable deployments to run with managed service accounts created by the gateway controller. The `consul.authentication.account` field is ignored when this option is enabled. | Boolean | `false` | -| `consul.authentication.method` | Specifies the Consul auth method used for initial authentication by Consul API Gateway. | String | N/A | -| `consul.authentication.namespace` | Specifies the Consul namespace to use for authentication. | String | N/A | -| `consul.ports.grpc` | Specifies the gRPC port for Consul's xDS server. | Integer | `8502` | -| `consul.ports.http` | Specifies the port for Consul's HTTP server. | Integer | `8500` | -| `consul.scheme` | Specifies the scheme to use for connecting to Consul. The supported values are `"http"` and `"https"`. | String | `"http"` | -| `copyAnnotations.service` | List of annotations to copy to the gateway service. | Array | `["external-dns.alpha.kubernetes.io/hostname"]` | -| `image.consulAPIGateway` | The image to use for consul-api-gateway. View available image tags on [DockerHub](https://hub.docker.com/r/hashicorp/consul-api-gateway/tags). | String | `"hashicorp/consul-api-gateway:RELEASE_VERSION"` | -| `image.envoy` | Specifies the container image to use for Envoy. View available image tags on [DockerHub](https://hub.docker.com/r/envoyproxy/envoy/tags). | String | `"envoyproxy/envoy:RELEASE_VERSION"` | -| `logLevel` | Specifies the error reporting level for logs. You can specify the following values: `error`, `warning`, `info`, `debug`, `trace`. | String | `"info"` | -| `nodeSelector` | Specifies a set of parameters that constrain the nodes on which the pod can run. Defining nodes with the `nodeSelector` enables the pod to fit on a node. The selector must match a node's labels for the pod to be scheduled on that node. Refer to the [Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/) for additional information. | Object | N/A | -| `serviceType` | Specifies the ingress methods for a service. The following values are supported:
`ClusterIP`
`NodePort`
`LoadBalancer`. | String | N/A | -| `useHostPorts` | If set to `true`, then the Envoy container ports are mapped to host ports. | Boolean | `false` | - -Refer to the [Consul API Gateway repository](https://github.com/hashicorp/consul-api-gateway/blob/main/config/crd/bases/api-gateway.consul.hashicorp.com_gatewayclassconfigs.yaml) for the complete specification. - -### GatewayClass - -The `GatewayClass` resource is used as a template for creating `Gateway` resources. -The specification includes the name of the controller (`controllerName`) and an API object containing controller-specific configuration resources within the cluster (`parametersRef`). -The value of the `controllerName` field must be set to `hashicorp.com/consul-api-gateway-controller`. - -When gateways are created from a `GatewayClass`, they use the parameters specified in the `GatewayClass` at the time of instantiation. - -Add the `kind: GatewayClass` option to the the gateway values file to declare a gateway class. -The following example creates a gateway class called `test-gateway-class`: - - - -```yaml -apiVersion: gateway.networking.k8s.io/v1alpha2 -kind: GatewayClass -metadata: - name: test-gateway-class -spec: - controllerName: 'hashicorp.com/consul-api-gateway-controller' - parametersRef: - group: api-gateway.consul.hashicorp.com - kind: GatewayClassConfig - name: test-gateway-class-config -``` - - - -Refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.GatewayClass) for details about configuring gateway classes. - -### Gateway - -The gateway configuration is the main infrastructure resource that links API gateway components. It specifies the name of the `GatewayClass` and one or more `listeners`. - -Add the `kind: Gateway` option to the configuration file to declare a gateway. -The following example creates a gateway called `example-gateway`. -The gateway is based on the `test-gateway-class` and includes a listener called `https` (see [Listeners](#listeners) for details about the `listener` configuration). - - - -```yaml -apiVersion: gateway.networking.k8s.io/v1alpha2 -kind: Gateway -metadata: - name: example-gateway - annotations: - 'external-dns.alpha.kubernetes.io/hostname': DNS_HOSTNAME -spec: - gatewayClassName: test-gateway-class - listeners: - - protocol: HTTPS - hostname: DNS_HOSTNAME - port: 443 - name: https - allowedRoutes: - namespaces: - from: Same - tls: - certificateRefs: - - name: gateway-production-certificate -``` - - - -Refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.Gateway) for details about configuring gateways: - -#### Listeners - -Listeners are the logical endpoints bound to the gateway's addresses. -Add the `listener` object to the `gateway` configuration and specify the following properties to define a listener: - -| Parameter | Description | Type | Default | -| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------- | -| `hostname` | Specifies the virtual hostname to match for protocol types. | String | none | -| `port` | Specifies the network port number. | Integer | none | -| `protocol` | Specifies the network protocol expected by the listener. | String | `http` | -| `tls` | Collection of parameters that specify TLS options for the listener. Refer to the [`GatewayTLSConfig`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.GatewayTLSConfig) documentation for additional information about configuring TLS. | Object | N/A | -| `tls.mode` | Specifies a mode for operating Consul API Gateway listeners over TLS.
You can only specify the `Terminate` mode, which configures the TLS session between the downstream client and the gateway to terminate at the gateway.
Refer to the [`TLSModeType` documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.TLSModeType) for additional information. | String | `Terminate` | -| `tls.certificateRefs` | Specifies the name of secret object used for Envoy SDS (Secret Discovery Service) to support terminating TLS. Refer to the [`[]*SecretObjectReference` documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.SecretObjectReference) for additional information. | String | N/A | -| `tls.options` | Specifies key/value pairs to enable extended TLS configuration specific to an implementation. | Object | N/A | -| `tls.options.tls_min_version` | Specifies the minimum TLS version supported for the listener. The following values are supported: `TLS_AUTO`, `TLSv1_0`, `TLSv1_1`, `TLSv1_2`, `TLSv1_3`. | String | `TLS 1.2` | -| `tls.options.tls_max_version` | Specifies the maximum TLS version supported for the listener. The specified version must be greater than or equal to `TLSMinVersion`. The following values are supported: `TLS_AUTO`, `TLSv1_0`, `TLSv1_1`, `TLSv1_2`, `TLSv1_3`. | String | `TLS 1.3` | -| `tls.options.tls_cipher_suites` | Specifies the list of TLS cipher suites to support when negotiating connections using TLS 1.2 or earlier.
If unspecified, a [more secure set of cipher suites](https://github.com/hashicorp/consul-api-gateway/blob/main/internal/common/tls.go#L3-L10) than Envoy's current [default server cipher list](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/transport_sockets/tls/v3/common.proto#envoy-v3-api-field-extensions-transport-sockets-tls-v3-tlsparameters-cipher-suites) will be used.
The full list of supported cipher suites can seen in [`internal/common/tls.go`](https://github.com/hashicorp/consul-api-gateway/blob/main/internal/common/tls.go) and is dependent on underlying support in Envoy. | String | See description | - -Refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.Listener) for details about configuring listeners. - -### Route - -Routes are independent configuration objects that are associated with specific listeners. - -Declare a route with either `kind: HTTPRoute` or `kind: TCPRoute` and configure the route parameters in the `spec` block. -Refer to the Kubernetes Gateway API documentation for each object type for details: - -- [HTTPRoute](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.HTTPRoute) -- [TCPRoute](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.TCPRoute) - -The following example creates a route named `example-route` associated with a listener defined in `example-gateway`. - - - -```yaml -apiVersion: gateway.networking.k8s.io/v1alpha2 -kind: HTTPRoute -metadata: - name: example-route -spec: - parentRefs: - - name: example-gateway - rules: - - backendRefs: - - kind: Service - name: echo - port: 8080 -``` - - - - -### MeshService - -MeshService holds a reference to an externally managed Consul Service Mesh service, and can be used as a `backendRef` for a [`Route`](#route). - -| Parameter | Description | Type | Default | -| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------- | -| `name` | Specifies the service name for a Consul service. It is assumed this service will exist in either the `consulDestinationNamespace` or mirrored Consul namespace from where this custom resource is defined, depending on the Helm configuration. - -Refer to the [Consul API Gateway repository](https://github.com/hashicorp/consul-api-gateway/blob/main/config/crd/bases/api-gateway.consul.hashicorp.com_meshservices.yaml) for the complete specification. diff --git a/website/content/docs/api-gateway/tech-specs.mdx b/website/content/docs/api-gateway/tech-specs.mdx index 12245b1848..eb5639dd28 100644 --- a/website/content/docs/api-gateway/tech-specs.mdx +++ b/website/content/docs/api-gateway/tech-specs.mdx @@ -7,7 +7,13 @@ description: >- # Technical Specifications -## Required Software and Supported Versions +This topic describes the technical specifications associated with using Consul API Gateway. + +## Requirements + +Verify that your environment meets the following requirements prior to using Consul API Gateway. + +### Datacenter Requirements Your datacenter must meet the following requirements prior to configuring the Consul API Gateway: @@ -16,6 +22,16 @@ Your datacenter must meet the following requirements prior to configuring the Co - Consul 1.11.2+ - HashiCorp Consul Helm chart 0.41.0+ +### TCP Port Requirements + +The following table describes the TCP port requirements for each component of the API Gateway. + +| Port | Description | Component | +| ---- | ----------- | --------- | +| 9090 | Secret discovery service (SDS) | Gateway controller pod
Gateway instance pod | +| 20000 | Kubernetes readiness probe | Gateway instance pod | +| Configurable | Port for scraping Prometheus metrics. Disabled by default. | Gateway controller pod | + ## Consul Server Deployments - Consul Editions supported: OSS and Enterprise @@ -39,36 +55,14 @@ Supported version of the Gateway API spec: v1alpha2 ## Resource Allocations -The tables below list the resource allocations for each component of the API Gateway. +The following resources are allocated for each component of the API Gateway. ### Gateway Controller Pod -| Resource | Allocation | -| -------- | -------------------------------------------------------------------------------------------------------- | -| CPU | None specified. Will use namespace or cluster default depending on the Kubernetes cluster configuration. | -| Memory | None specified. Will use namespace or cluster default depending on the Kubernetes cluster configuration. | +* **CPU**: None. Either the namespace or cluster default is allocated, depending on the Kubernetes cluster configuration. +* **Memory**: None. Either the the namespace or cluster default is allocated, depending on the Kubernetes cluster configuration. ### Gateway Instance Pod -| Resource | Allocation | -| -------- | -------------------------------------------------------------------------------------------------------- | -| CPU | None specified. Will use namespace or cluster default depending on the Kubernetes cluster configuration. | -| Memory | None specified. Will use namespace or cluster default depending on the Kubernetes cluster configuration. | - -## TCP Ports Required - -The tables below list the TCP ports that are used by each component of the API Gateway. - -### Gateway Controller Pod - -| Port | Used For | -| ---- | ------------------------------------------------------------------ | -| 9090 | Secret Discovery Service (SDS) | -| Configurable | Port for scraping Prometheus metrics. Disabled by default. | - -### Gateway Instance Pod - -| Port | Used For | -| ----- | ----------------------------- | -| 9090 | Secret Discovery Service (SDS) | -| 20000 | Kubernetes readiness probe | +* **CPU**: None. Either the namespace or cluster default is allocated, depending on the Kubernetes cluster configuration. +* **Memory**: None. Either the namespace or cluster default is allocated, depending on the Kubernetes cluster configuration. \ No newline at end of file diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 51077a327b..0130d1f472 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -381,6 +381,10 @@ "title": "Overview", "path": "api-gateway" }, + { + "title": "Usage", + "path": "api-gateway/api-gateway-usage" + }, { "title": "Technical Specifications", "path": "api-gateway/tech-specs"