From ec112f0d3cefbd56f30cc0fa2f646f0652b79662 Mon Sep 17 00:00:00 2001 From: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> Date: Thu, 17 Nov 2022 15:42:25 -0800 Subject: [PATCH] Update docs for the release of Consul API Gateway v0.5 (#15015) * added usage folder to organize use case docs for CAPIgw * Add peer field to MeshService configuration page * Add first pass at guide for routing to peered services * Add exception to same-datacenter restriction for referenced Consul service * Add example HTTPRoute referencing the MeshService as backendRef * Add example ServiceResolver * Add note about current ServiceResolver requirement ServiceResolver may eventually be created implicitly by the API gateway controller, but that decision is pending. * tweaks to the usage page for routing to peered services * tweaks to the description in the configuration reference * resolved TO-DOs from previous iteration * Remove datacenter federation from limited support matrix * added tolerations doc * Remove note excluding k8s 1.24 since we now support it * Reorder sections to maintain alphabetical sort * Add example configuration for MeshService resource * Adjust wording + indentation of other docs * Use consistent "example-" prefix for resource names in example code * reframed the tolerations documentation; STILL A WIP * add helm chart documentation * removed tolerations from gwcconfig configuration model reference * Apply suggestions from code review Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> * update version to 0.5.0 * Update install.mdx * added release notes for v.0.5.x Co-authored-by: Nathan Coleman Co-authored-by: Sarah Alsmiller Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> Co-authored-by: sarahalsmiller <100602640+sarahalsmiller@users.noreply.github.com> --- .../configuration/gatewayclass.mdx | 26 ++--- .../configuration/gatewayclassconfig.mdx | 4 +- .../api-gateway/configuration/meshservice.mdx | 35 +++++- website/content/docs/api-gateway/install.mdx | 4 +- .../content/docs/api-gateway/tech-specs.mdx | 6 +- .../content/docs/api-gateway/usage/errors.mdx | 60 ++++++++++ .../usage/reroute-http-requests.mdx | 58 ++++++++++ .../usage/route-to-peered-services.mdx | 76 ++++++++++++ .../docs/api-gateway/{ => usage}/usage.mdx | 108 ++---------------- website/content/docs/k8s/helm.mdx | 30 ++--- .../consul-api-gateway/v0_5_x.mdx | 56 +++++++++ website/data/docs-nav-data.json | 24 +++- 12 files changed, 347 insertions(+), 140 deletions(-) create mode 100644 website/content/docs/api-gateway/usage/errors.mdx create mode 100644 website/content/docs/api-gateway/usage/reroute-http-requests.mdx create mode 100644 website/content/docs/api-gateway/usage/route-to-peered-services.mdx rename website/content/docs/api-gateway/{ => usage}/usage.mdx (55%) create mode 100644 website/content/docs/release-notes/consul-api-gateway/v0_5_x.mdx diff --git a/website/content/docs/api-gateway/configuration/gatewayclass.mdx b/website/content/docs/api-gateway/configuration/gatewayclass.mdx index 8150860be..152926be8 100644 --- a/website/content/docs/api-gateway/configuration/gatewayclass.mdx +++ b/website/content/docs/api-gateway/configuration/gatewayclass.mdx @@ -58,22 +58,22 @@ Specifies a human-readable description of the gateway class. We recommend using * Required: optional ## Example Configuration -The following example creates a gateway class called `test-gateway-class`: +The following example creates a gateway class called `example-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 - description: The gateway class is for creating test gateways class configurations +```yaml +apiVersion: gateway.networking.k8s.io/v1alpha2 +kind: GatewayClass +metadata: + name: example-gateway-class +spec: + controllerName: 'hashicorp.com/consul-api-gateway-controller' + parametersRef: + group: api-gateway.consul.hashicorp.com + kind: GatewayClassConfig + name: example-gateway-class-config + description: The gateway class is for creating test gateways class configurations ``` diff --git a/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx b/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx index 2aba34773..8f83a6cd8 100644 --- a/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx +++ b/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx @@ -178,7 +178,7 @@ If set to `true`, then the Envoy container ports are mapped to host ports. ## Example Configuration -The following example creates a gateway class configuration called `test-gateway-class-config`. Traffic that passes through gateways created from the class configuration authenticate with Consul over HTTPS on port `8501`. Consul client agents communicate with server agents on port `8502` : +The following example creates a gateway class configuration called `example-gateway-class-config`. Traffic that passes through gateways created from the class configuration authenticates with Consul over HTTPS on port `8501`. Consul client agents communicate with server agents on port `8502`: @@ -186,7 +186,7 @@ The following example creates a gateway class configuration called `test-gateway apiVersion: api-gateway.consul.hashicorp.com/v1alpha1 kind: GatewayClassConfig metadata: - name: test-gateway-class-config + name: example-gateway-class-config spec: useHostPorts: true logLevel: 'trace' diff --git a/website/content/docs/api-gateway/configuration/meshservice.mdx b/website/content/docs/api-gateway/configuration/meshservice.mdx index 2dd377fb6..8b13b2dd0 100644 --- a/website/content/docs/api-gateway/configuration/meshservice.mdx +++ b/website/content/docs/api-gateway/configuration/meshservice.mdx @@ -11,14 +11,17 @@ This topic provides full details about the `MeshService` resource. ## Introduction -A `MeshService` is a resource in the Kubernetes cluster that enables Kubernetes configuration models, such as `HTTPRoute` and `TCPRoute`, to reference services that only exist in Consul. A `MeshService` represents a service in the Consul service mesh outside the Kubernetes cluster where Consul API Gateway is deployed. The service represented by the `MeshService` resource must be in the same Consul datacenter as the Kubernetes cluster. +A `MeshService` is a resource in the Kubernetes cluster that enables Kubernetes configuration models, such as `HTTPRoute` and `TCPRoute`, to reference services that only exist in Consul. +A `MeshService` represents a service in the Consul service mesh outside the Kubernetes cluster where Consul API Gateway is deployed. +The service represented by the `MeshService` resource must either be in the same Consul datacenter as the Kubernetes cluster or imported from a peered Consul cluster. ## Configuration Model The following outline shows how to format the configurations in the `MeshService` object. Click on a property name to view details about the configuration. -* [`name`](#name): string | required +- [`name`](#name): string | required +- [`peer`](#peer): string | optional ## Specification @@ -27,5 +30,29 @@ This topic provides details about the configuration parameters. ### name Specifies the name of the service in the Consul service mesh to send traffic to. -* Type: string -* Required: required +- Type: string +- Required: required + +### peer +Specifies the name of the peered Consul cluster that exported the service. If not specified, Consul defaults to the local datacenter. + +You must apply a [`ServiceResolver`](/docs/connect/config-entries/service-resolver) for the referenced service. The `ServiceResolver` configuration entry enables Consul to resolve routes to upstream service instances. + +- Type: string +- Required: optional + +## Example Configuration + +The following example creates a mesh service called `example-mesh-service`. Routes that use `example-mesh-service` as a backend route traffic to the Consul service in the local datacenter named `echo`. + + + +```yaml hideClipboard +apiVersion: api-gateway.consul.hashicorp.com/v1alpha1 +kind: MeshService +metadata: + name: example-mesh-service +spec: + name: echo +``` + diff --git a/website/content/docs/api-gateway/install.mdx b/website/content/docs/api-gateway/install.mdx index ac6e36ab6..5f2470de6 100644 --- a/website/content/docs/api-gateway/install.mdx +++ b/website/content/docs/api-gateway/install.mdx @@ -18,7 +18,7 @@ Ensure that the environment you are deploying Consul API Gateway in meets the re 1. Set the version of Consul API Gateway you are installing as an environment variable. The following steps use this environment variable in commands and configurations. ```shell-session - $ export VERSION=0.3.0 + $ export VERSION=0.5.0 ``` 1. Issue the following command to install the CRDs: @@ -76,7 +76,7 @@ Ensure that the environment you are deploying Consul API Gateway in meets the re Install Consul with API Gateway on your Kubernetes cluster by specifying the `values.yaml` file. ```shell-session - $ helm install consul hashicorp/consul --version 0.45.0 --values values.yaml --create-namespace --namespace consul + $ helm install consul hashicorp/consul --version 1.0.0 --values values.yaml --create-namespace --namespace consul ``` diff --git a/website/content/docs/api-gateway/tech-specs.mdx b/website/content/docs/api-gateway/tech-specs.mdx index b0a0e4fad..b90706c3f 100644 --- a/website/content/docs/api-gateway/tech-specs.mdx +++ b/website/content/docs/api-gateway/tech-specs.mdx @@ -18,7 +18,6 @@ Verify that your environment meets the following requirements prior to using Con Your datacenter must meet the following requirements prior to configuring the Consul API Gateway: - Kubernetes 1.21+ - - Kubernetes 1.24 is not supported at this time. - `kubectl` 1.21+ - Consul 1.11.2+ - HashiCorp Consul Helm chart 0.47.1+ @@ -48,9 +47,8 @@ The following table lists API Gateway limitations related to specific Consul fea | Consul Feature | Limitation | | -------------- | ---------- | -| [Admin partitions](/docs/enterprise/admin-partitions) | You can only deploy Consul API Gateway into the `default` admin partition and it can only route to other services within that partition, i.e. you cannot route to services in other admin partitions. | -| Datacenter federation | If you are connecting multiple Consul datacenters to create a federated network, you can only deploy Consul API Gateway in the `primary` datacenter. | -| Routing between datacenters | If you are connecting multiple Consul datacenters to create a federated network, API Gateway can only route traffic to Services in the local datacenter. However, API Gateway can route to Services in other Kubernetes clusters when they are in the same Consul datacenter. Refer to [Single Consul Datacenter in Multiple Kubernetes Clusters](/docs/k8s/deployment-configurations/single-dc-multi-k8s) for more details. | +| [Admin partitions](/docs/enterprise/admin-partitions) | You can deploy Consul API Gateway into the `default` admin partition only. You can route to services in other `default` admin partitions through peered connections. Refer to [Route Traffic to Peered Services](/consul/docs/api-gateway/usage/route-to-peered-services) for additional information. | +| Routing between datacenters | If you are connecting multiple Consul datacenters to create a federated network, you can route to services in other datacenters through peered connections. Refer to [Route Traffic to Peered Services](/consul/docs/api-gateway/usage/route-to-peered-services) for additional information. | ## Deployment Environments diff --git a/website/content/docs/api-gateway/usage/errors.mdx b/website/content/docs/api-gateway/usage/errors.mdx new file mode 100644 index 000000000..779f27344 --- /dev/null +++ b/website/content/docs/api-gateway/usage/errors.mdx @@ -0,0 +1,60 @@ +--- +layout: docs +page_title: Consul API Gateway Error Messages +description: >- + Learn how to apply a configured Consul API Gateway to your Kubernetes cluster, review the required fields for rerouting HTTP requests, and troubleshoot an error message. +--- + +# Error Messages + +This topic provides information about potential error messages associated with Consul API Gateway. If you receive an error message that does not appear in this section, refer to the following resources: + +- [Common Consul errors](/docs/troubleshoot/common-errors#common-errors-on-kubernetes) +- [Consul troubleshooting guide](/docs/troubleshoot/common-errors) +- [Consul Discuss forum](https://discuss.hashicorp.com/) + + + +## Helm installation failed: "no matches for kind" + +```log +Error: INSTALLATION FAILED: unable to build kubernetes objects from release manifest: [unable to recognize "": no matches for kind "GatewayClass" in version "gateway.networking.k8s.io/v1alpha2", unable to recognize "": no matches for kind "GatewayClassConfig" in version "api-gateway.consul.hashicorp.com/v1alpha1"] +``` +**Conditions:** +Consul API Gateway generates this error when the required CRD files have not been installed in Kubernetes prior to installing Consul API Gateway. + +**Impact:** +The installation process typically fails after this error message is generated. + +**Resolution:** +Install the required CRDs. Refer to the [Consul API Gateway installation instructions](/docs/api-gateway/install#installation) for instructions. \ No newline at end of file diff --git a/website/content/docs/api-gateway/usage/reroute-http-requests.mdx b/website/content/docs/api-gateway/usage/reroute-http-requests.mdx new file mode 100644 index 000000000..cdb7c8ce1 --- /dev/null +++ b/website/content/docs/api-gateway/usage/reroute-http-requests.mdx @@ -0,0 +1,58 @@ +--- +layout: docs +page_title: Reroute HTTP Requests +description: >- + Learn how to configure Consul API Gateway to reroute HTTP requests to a specific path. +--- + +# Reroute HTTP Requests + +This topic describes how to configure Consul API Gateway to reroute HTTP requests. + +## Requirements + +1. Verify that the [requirements](/docs/api-gateway/tech-specs) have been met. +1. Verify that the Consul API Gateway CRDs and controller have been installed and applied. Refer to [Installation](/docs/api-gateway/install) for details. + +## Configuration + +Specify the following fields in your `Route` configuration. Refer to the [Route configuration reference](/docs/api-gateway/configuration/routes) for details about the parameters. + +- [`rules.filters.type`](/docs/api-gateway/configuration/routes#rules-filters-type): Set this parameter to `URLRewrite` to instruct Consul API Gateway to rewrite the URL when specific conditions are met. +- [`rules.filters.urlRewrite`](/docs/api-gateway/configuration/routes#rules-filters-urlrewrite): Specify the `path` configuration. +- [`rules.filters.urlRewrite.path`](/docs/api-gateway/configuration/routes#rules-filters-urlrewrite-path): Contains the paths that incoming requests should be rewritten to based on the match conditions. + +To configure the route to accept paths with or without a trailing slash, you must make two separate routes to handle each case. + +### Example + +In the following example, requests to` /incoming-request-prefix/` are forwarded to the `backendRef` as `/prefix-backend-receives/`. As a result, requests to `/incoming-request-prefix/request-path` are received by `backendRef` as `/prefix-backend-receives/request-path`. + + + +```yaml hideClipboard +apiVersion: gateway.networking.k8s.io/v1beta1 +kind: HTTPRoute +metadata: + name: example-route + ##... +spec: + parentRefs: + - group: gateway.networking.k8s.io + kind: Gateway + name: api-gateway + rules: + - backendRefs: + . . . + filters: + - type: URLRewrite + urlRewrite: + path: + replacePrefixMatch: /prefix-backend-receives/ + type: ReplacePrefixMatch + matches: + - path: + type: PathPrefix + value: /incoming–request-prefix/ +``` + \ No newline at end of file diff --git a/website/content/docs/api-gateway/usage/route-to-peered-services.mdx b/website/content/docs/api-gateway/usage/route-to-peered-services.mdx new file mode 100644 index 000000000..cfd748f80 --- /dev/null +++ b/website/content/docs/api-gateway/usage/route-to-peered-services.mdx @@ -0,0 +1,76 @@ +--- +page_title: Route Traffic to Peered Services +description: Learn how to configure Consul API Gateway to route traffic to services connected to the mesh through a peering connection. +--- + +# Route Traffic to Peered Services + +This topic describes how to configure Consul API Gateway to route traffic to services connected to the mesh through a cluster peering connection. + +## Requirements + +1. Consul 1.14 or later +1. Verify that the [requirements](/docs/api-gateway/tech-specs) have been met. +1. Verify that the Consul API Gateway CRDs and controller have been installed and applied. Refer to [Installation](/docs/api-gateway/install) for details. +1. A peering connection must already be established between Consul clusters. Refer to [Cluster Peering on Kubernetes](/docs/connect/cluster-peering/k8s) for instructions. +1. The Consul service that you want to route traffic to must be exported to the cluster containing your `Gateway`. Refer to [Cluster Peering on Kubernetes](/docs/connect/cluster-peering/k8s) for instructions. +1. A `ServiceResolver` for the Consul service you want to route traffic to must be created in the cluster that contains your `Gateway`. Refer to [Service Resolver Configuration Entry](/docs/connect/config-entries/service-resolver) for instructions. + +## Configuration + +Specify the following fields in your `MeshService` configuration to use this feature. Refer to the [MeshService configuration reference](/docs/api-gateway/configuration/mesh) for details about the parameters. + +- [`name`](/docs/api-gateway/configuration/meshservice#name) +- [`peer`](/docs/api-gateway/configuration/meshservice#peer) + +## Example + +In the following example, routes that use `example-mesh-service` as a backend are configured to send requests to the `echo` service exported by the peered Consul cluster `cluster-02`. + + + +```yaml hideClipboard +apiVersion: consul.hashicorp.com/v1alpha1 +kind: ServiceResolver +metadata: + name: echo +spec: + redirect: + peer: cluster-02 + service: echo +``` + + + + +```yaml hideClipboard +apiVersion: api-gateway.consul.hashicorp.com/v1alpha1 +kind: MeshService +metadata: + name: example-mesh-service +spec: + name: echo + peer: cluster-02 +``` + + +After applying the `meshservice.yaml` configuration, an `HTTPRoute` may then reference `example-mesh-service` as its `backendRef`. + + + +```yaml hideClipboard +apiVersion: gateway.networking.k8s.io/v1beta1 +kind: HTTPRoute +metadata: + name: example-route +spec: + ... + rules: + - backendRefs: + - group: api-gateway.consul.hashicorp.com + kind: MeshService + name: example-mesh-service + port: 3000 + ... +``` + diff --git a/website/content/docs/api-gateway/usage.mdx b/website/content/docs/api-gateway/usage/usage.mdx similarity index 55% rename from website/content/docs/api-gateway/usage.mdx rename to website/content/docs/api-gateway/usage/usage.mdx index f5199d0c8..aaac259d0 100644 --- a/website/content/docs/api-gateway/usage.mdx +++ b/website/content/docs/api-gateway/usage/usage.mdx @@ -5,17 +5,20 @@ description: >- Learn how to apply a configured Consul API Gateway to your Kubernetes cluster, review the required fields for rerouting HTTP requests, and troubleshoot an error message. --- -# Use Consul API Gateway +# Basic Consul API Gateway Usage This topic describes how to use Consul API Gateway. -## Basic usage +## Requirements Complete the following steps to use Consul API Gateway in your network. 1. Verify that the [requirements](/docs/api-gateway/tech-specs) have been met. 1. Verify that the Consul API Gateway CRDs and controller have been installed and applied. Refer to [Installation](/docs/api-gateway/install) for details. -1. Configure your [`Gateway`](/docs/api-gateway/configuration/gateway) and [`Routes`](/docs/api-gateway/configuration/routes) as describe in the [Configuration](/docs/api-gateway/configuration) section. + +## Configuration + +Configure your [`Gateway`](/docs/api-gateway/configuration/gateway) and [`Routes`](/docs/api-gateway/configuration/routes) as described in [Consul API Gateway Configuration](/docs/api-gateway/configuration). @@ -27,55 +30,14 @@ Complete the following steps to use Consul API Gateway in your network. -1. Issue the `kubectl apply` command to implement the configurations: +## Apply configurations + +Issue the `kubectl apply` command to implement the configurations: ```shell-session $ kubectl apply -f gateway.yaml routes.yaml ``` -## Reroute HTTP requests - -Configure the following fields in your `Route` configuration to use this feature. Refer to the [Route configuration reference](/docs/api-gateway/configuration/routes) for details about the parameters. - -* [`rules.filters.type`](/docs/api-gateway/configuration/routes#rules-filters-type): Set this parameter to `URLRewrite` to instruct Consul API Gateway to rewrite the URL when specific conditions are met. -* [`rules.filters.urlRewrite`](/docs/api-gateway/configuration/routes#rules-filters-urlrewrite): Specify the `path` configuration. -* [`rules.filters.urlRewrite.path`](/docs/api-gateway/configuration/routes#rules-filters-urlrewrite-path): Contains the paths that incoming requests should be rewritten to based on the match conditions. - -Note that if the route is configured to accept paths with and without a trailing slash, you must make two separate routes to handle each case. - -### Example - -In the following example, requests to` /incoming-request-prefix/` are forwarded to the `backendRef` as `/prefix-backend-receives/`. A request to `/incoming-request-prefix/request-path`, for instance, is received by the `backendRef` as `/prefix-backend-receives/request-path`. - - - -```yaml hideClipboard -apiVersion: gateway.networking.k8s.io/v1beta1 -kind: HTTPRoute -metadata: - name: example-route - ##... -spec: - parentRefs: - - group: gateway.networking.k8s.io - kind: Gateway - name: api-gateway - rules: - - backendRefs: - . . . - filters: - - type: URLRewrite - urlRewrite: - path: - replacePrefixMatch: /prefix-backend-receives/ - type: ReplacePrefixMatch - matches: - - path: - type: PathPrefix - value: /incoming–request-prefix/ -``` - - -## Error Messages -This topic provides information about potential error messages associated with Consul API Gateway. If you receive an error message that does not appear in this section, refer to the following resources: - -* [Common Consul errors](/docs/troubleshoot/common-errors#common-errors-on-kubernetes) -* [Consul troubleshooting guide](/docs/troubleshoot/common-errors) -* [Consul Discuss forum](https://discuss.hashicorp.com/) - - - -### Helm installation failed: "no matches for kind" - -```log -Error: INSTALLATION FAILED: unable to build kubernetes objects from release manifest: [unable to recognize "": no matches for kind "GatewayClass" in version "gateway.networking.k8s.io/v1alpha2", unable to recognize "": no matches for kind "GatewayClassConfig" in version "api-gateway.consul.hashicorp.com/v1alpha1"] -``` -**Conditions:** -Consul API Gateway generates this error when the required CRD files have not been installed in Kubernetes prior to installing Consul API Gateway. - -**Impact:** -The installation process typically fails after this error message is generated. - -**Recommended Action:** -Install the required CRDs by using the command in Step 1 of the [Consul API Gateway installation instructions](/docs/api-gateway/install#installation) and then retry installing Consul API Gateway. diff --git a/website/content/docs/k8s/helm.mdx b/website/content/docs/k8s/helm.mdx index 84cc28fda..c36b86e6b 100644 --- a/website/content/docs/k8s/helm.mdx +++ b/website/content/docs/k8s/helm.mdx @@ -247,14 +247,14 @@ Use these links to navigate to a particular top-level stanza. - `controller` ((#v-global-secretsbackend-vault-controller)) - - `tlsCert` ((#v-global-secretsbackend-vault-controller-tlscert)) - Configuration to the Vault Secret that Kubernetes will use on + - `tlsCert` ((#v-global-secretsbackend-vault-controller-tlscert)) - Configuration to the Vault Secret that Kubernetes uses on Kubernetes CRD creation, deletion, and update, to get TLS certificates used issued from vault to send webhooks to the controller. - `secretName` ((#v-global-secretsbackend-vault-controller-tlscert-secretname)) (`string: null`) - The Vault secret path that issues TLS certificates for controller webhooks. - - `caCert` ((#v-global-secretsbackend-vault-controller-cacert)) - Configuration to the Vault Secret that Kubernetes will use on + - `caCert` ((#v-global-secretsbackend-vault-controller-cacert)) - Configuration to the Vault Secret that Kubernetes uses on Kubernetes CRD creation, deletion, and update, to get CA certificates used issued from vault to send webhooks to the controller. @@ -263,14 +263,14 @@ Use these links to navigate to a particular top-level stanza. - `connectInject` ((#v-global-secretsbackend-vault-connectinject)) - - `caCert` ((#v-global-secretsbackend-vault-connectinject-cacert)) - Configuration to the Vault Secret that Kubernetes will use on + - `caCert` ((#v-global-secretsbackend-vault-connectinject-cacert)) - Configuration to the Vault Secret that Kubernetes uses on Kubernetes pod creation, deletion, and update, to get CA certificates used issued from vault to send webhooks to the ConnectInject. - `secretName` ((#v-global-secretsbackend-vault-connectinject-cacert-secretname)) (`string: null`) - The Vault secret path that contains the CA certificate for Connect Inject webhooks. - - `tlsCert` ((#v-global-secretsbackend-vault-connectinject-tlscert)) - Configuration to the Vault Secret that Kubernetes will use on + - `tlsCert` ((#v-global-secretsbackend-vault-connectinject-tlscert)) - Configuration to the Vault Secret that Kubernetes uses on Kubernetes pod creation, deletion, and update, to get TLS certificates used issued from vault to send webhooks to the ConnectInject. @@ -518,7 +518,7 @@ Use these links to navigate to a particular top-level stanza. - `enabled` ((#v-global-openshift-enabled)) (`boolean: false`) - If true, the Helm chart will create necessary configuration for running its components on OpenShift. - - `consulAPITimeout` ((#v-global-consulapitimeout)) (`string: 5s`) - The time in seconds that the consul API client will wait for a response from + - `consulAPITimeout` ((#v-global-consulapitimeout)) (`string: 5s`) - The time in seconds that the consul API client waits for a response from the API before cancelling the request. - `cloud` ((#v-global-cloud)) - Enables installing an HCP Consul self-managed cluster. @@ -662,7 +662,7 @@ Use these links to navigate to a particular top-level stanza. storage classes, the PersistentVolumeClaims would need to be manually created. A `null` value will use the Kubernetes cluster's default StorageClass. If a default StorageClass does not exist, you will need to create one. - Refer to the [Read/Write Tuning](https://www.consul.io/docs/install/performance#read-write-tuning) + Refer to the [Read/Write Tuning](/consul/docs/install/performance#read-write-tuning) section of the Server Performance Requirements documentation for considerations around choosing a performant storage class. @@ -1563,9 +1563,9 @@ Use these links to navigate to a particular top-level stanza. - `disruptionBudget` ((#v-connectinject-disruptionbudget)) - This configures the PodDisruptionBudget (https://kubernetes.io/docs/tasks/run-application/configure-pdb/) for the service mesh sidecar injector. - - `enabled` ((#v-connectinject-disruptionbudget-enabled)) (`boolean: true`) - This will enable/disable registering a PodDisruptionBudget for the - service mesh sidecar injector. If this is enabled, it will only register the budget so long as - the service mesh is enabled. + - `enabled` ((#v-connectinject-disruptionbudget-enabled)) (`boolean: true`) - Enables registering a PodDisruptionBudget for the + service mesh sidecar injector. If enabled, it only registers the budget so long as + the service mesh is enabled. To disable, set to `false`. - `maxUnavailable` ((#v-connectinject-disruptionbudget-maxunavailable)) (`integer: null`) - The maximum number of unavailable pods. By default, this will be automatically computed based on the `connectInject.replicas` value to be `(n/2)-1`. @@ -1578,7 +1578,7 @@ Use these links to navigate to a particular top-level stanza. - `cni` ((#v-connectinject-cni)) - Configures consul-cni plugin for Consul Service mesh services - - `enabled` ((#v-connectinject-cni-enabled)) (`boolean: false`) - If true, then all traffic redirection setup will use the consul-cni plugin. + - `enabled` ((#v-connectinject-cni-enabled)) (`boolean: false`) - If true, then all traffic redirection setup uses the consul-cni plugin. Requires connectInject.enabled to also be true. - `logLevel` ((#v-connectinject-cni-loglevel)) (`string: null`) - Log level for the installer and plugin. Overrides global.logLevel @@ -2303,9 +2303,9 @@ Use these links to navigate to a particular top-level stanza. beta.kubernetes.io/arch: amd64 ``` - - `tolerations` ((#v-apigateway-managedgatewayclass-tolerations)) (`string: null`) - This value defines the tolerations that will be assigned to a gateway pod. - This should be a multi-line string matching the - Tolerations (https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/) array in a Pod spec. + - `tolerations` ((#v-apigateway-managedgatewayclass-tolerations)) (`string: ""`) - Toleration settings for gateway pods created with the managed gateway class. This + should be a multi-line string matching the [Tolerations] + (https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/) array in a Pod spec. - `serviceType` ((#v-apigateway-managedgatewayclass-servicetype)) (`string: LoadBalancer`) - This value defines the type of service created for gateways (e.g. LoadBalancer, ClusterIP) @@ -2370,8 +2370,8 @@ Use these links to navigate to a particular top-level stanza. beta.kubernetes.io/arch: amd64 ``` - - `tolerations` ((#v-apigateway-controller-tolerations)) (`string: null`) - This value defines the tolerations for api-gateway-controller pod, this should be a multi-line string matching the - Tolerations (https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/) array in a Pod spec. + - `tolerations` ((#v-apigateway-controller-tolerations)) (`string: null`) - Tolerations settings for the `api-gateway-controller` pod. This should be a multi-line string matching the + [Tolerations](https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/) array in a Pod spec. - `service` ((#v-apigateway-controller-service)) - Configuration for the Service created for the api-gateway-controller diff --git a/website/content/docs/release-notes/consul-api-gateway/v0_5_x.mdx b/website/content/docs/release-notes/consul-api-gateway/v0_5_x.mdx new file mode 100644 index 000000000..040433a8e --- /dev/null +++ b/website/content/docs/release-notes/consul-api-gateway/v0_5_x.mdx @@ -0,0 +1,56 @@ +--- +layout: docs +page_title: 0.5.x +description: >- + Learn about the changes to Consul API Gateway in version 0.5.x, including support for Consul Dataplane, routing to services in peered clusters, distroless Envoy containers, and Kubernetes tolerations +--- + +# Consul API Gateway 0.5.0 + +We are pleased to announce the following updates to Consul API Gateway. + +## Release highlights + +- **Consul Dataplane Support:** Consul 1.14 introduces a simplified deployment architecture that eliminates the need to deploy node-level Consul clients on Kubernetes. This is referred to as Consul Dataplane. API Gateway 0.5.0 supports this type of deployment. + +- **Routing to Services in Peered Clusters:** API Gateway now supports the ability to route traffic to services that are imported from peered Consul clusters. Cluster peering is was added in Consul 1.14. Refer to the `MeshService` [documentation](/docs/api-gateway/configuration/meshservice) for additional information. + +- **Deploy in Admin Partitions:** API Gateway can now be deployed in any Consul admin partition. Previous versions of API Gateway could only be deployed in the default partition. The partition is configured in the `GatewayClassConfig`. + +- **Configure Maximum Incoming Connections:** You can now configure the number of concurrent incoming connections that Envoy will allow. This is configured by setting the value of the `maxConnection` parameter in the `GatewayClassConfig`. + +- **Distroless Envoy Containers:** API Gateway now uses the `envoy-distroless` container image of the Envoy proxy. This improves the security of a gateway by reducing the attack surface of Envoy. Consul Helm chart `1.0.0` or greater is required to use the distroless container image. + +- **Support for Kubernetes Tolerations:** You can now configure toleration settings for the Consul API Gateway controller and Gateway instances made with the managed gateway class directly from the [Helm chart](/docs/k8s/helm#h-apigateway). Kubernetes toleration settings allow you to control which nodes in a K8s cluster that the API Gateway pods should be deployed on. Refer to [Taints and Tolerations](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) in the Kubernetes documentation for more information. + +## Supported software + +- Consul 1.12.0+ +- HashiCorp Consul Helm chart: + - 0.49.1+ for Consul 1.12 - 1.13 + - 1.0.0+ for Consul 1.14+ +- Kubernetes 1.21+ + - Kubernetes 1.25 is not supported at this time. +- Kubectl 1.21+ +- Envoy proxy support is determined by the Consul version deployed. Refer to [Envoy Integration](/docs/connect/proxies/envoy) for details. + +## Kubernetes Gateway API specification + +Supported version of the [Gateway API](https://gateway-api.sigs.k8s.io/) spec: v0.5.0 + +## Upgrading + +For detailed information on upgrading, please refer to the [Upgrades page](/docs/api-gateway/upgrades) + +## Known issues +At the time of release, there are no known issues in API Gateway v0.5.0 + + +## Changelogs + +The changelogs for this major release version and any maintenance versions are listed below. + +~> **Note:** The following link will take you to the changelogs on the GitHub website. + +- [0.5.0](https://github.com/hashicorp/consul-api-gateway/releases/tag/v0.5.0) + diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 0f8cd5449..39442e11d 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -183,6 +183,10 @@ { "title": "Consul API Gateway", "routes": [ + { + "title": "v0.5.x", + "path": "release-notes/consul-api-gateway/v0_5_x" + }, { "title": "v0.4.x", "path": "release-notes/consul-api-gateway/v0_4_x" @@ -1288,7 +1292,25 @@ }, { "title": "Usage", - "path": "api-gateway/usage" + "routes": [ + { + "title": "Basic Usage", + "path": "api-gateway/usage/usage" + }, + { + "title": "Reroute HTTP Requests", + "path": "api-gateway/usage/reroute-http-requests" + }, + { + "title": "Route Traffic to Peered Services", + "path": "api-gateway/usage/route-to-peered-services" + }, + { + "title": "Error Messages", + "path": "api-gateway/usage/errors" + } + + ] }, { "title": "Configuration",