diff --git a/website/content/docs/api-gateway/common-errors.mdx b/website/content/docs/api-gateway/common-errors.mdx deleted file mode 100644 index f49c9fefc549..000000000000 --- a/website/content/docs/api-gateway/common-errors.mdx +++ /dev/null @@ -1,67 +0,0 @@ ---- -layout: docs -page_title: Common Error Messages ---- - -# Common Error Messages - -Some of the errors messages commonly encountered during installation and operations of Consul API Gateway are listed below, along with suggested methods for resolving them. - -If the error message is not listed on this page, it may be listed on the main [Consul Common errors][consul-common-errors] page. If the error message is not listed on that page either, please consider following our general [Troubleshooting Guide][troubleshooting] or reach out to us in [Discuss](https://discuss.hashicorp.com/). - - - -### Helm installation failed: "no matches for kind" - -``` -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:** -When this error occurs during the process of installing Consul API Gateway, it is usually caused by not having the required CRD files installed in Kubernetes prior to installing Consul API Gateway. - -**Impact:** -The installation process will typically fail 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][install-instructions] and then retry installing Consul API Gateway. - - - - - -[consul-common-errors]: /docs/troubleshoot/common-errors -[troubleshooting]: https://learn.hashicorp.com/consul/day-2-operations/advanced-operations/troubleshooting -[install-instructions]: /docs/api-gateway/consul-api-gateway-install#installation \ No newline at end of file diff --git a/website/content/docs/api-gateway/configuration/gateway.mdx b/website/content/docs/api-gateway/configuration/gateway.mdx new file mode 100644 index 000000000000..94b48084584d --- /dev/null +++ b/website/content/docs/api-gateway/configuration/gateway.mdx @@ -0,0 +1,185 @@ +--- +layout: docs +page_title: Consul API Gateway Gateway +description: >- + This topic descrbes how to configure the Consul API Gateway Gateway object +--- + +# Gateway + +This topic provides full details about the `Gateway` resource. + +## Introduction + +A `Gateway` is an instance of network infrastructure that determines how service traffic should be handled. A `Gateway` contains one or more [`listeners`](#listeners) that bind to a set of IP addresses. An `HTTPRoute` or `TCPRoute` can then attach to a gateway listener to direct traffic from the gateway to a service. + +Gateway instances derive their configurations from the [`GatewayClass`](/docs/api-gateway/configuration/gatewayclass) resource, which acts as a template for individual `Gateway` deployments. Refer to [GatewayClass](/docs/api-gateway/configuration/gatewayclass) for additional information. + +Specify the following parameters to declare a `Gateway`: + +| Parameter | Description | Required | +| :----------- |:---------------------------------------------------------------------------------------------------------------------------------------------------------- |:-------- | +| `kind` | Specifies the type of configuration object. The value should always be `Gateway`. | Required | +| `description` | Human-readable string that describes the purpose of the `Gateway`. | Optional | +| `version ` | Specifies the Kubernetes API version. The value should always be `gateway.networking.k8s.io/v1alpha2` | Required | +| `scope` | Specifies the effective scope of the Gateway. The value should always be `namespaced`. | Required | +| `fields` | Specifies the configurations for the Gateway. The fields are listed in the [configuration model](#configuration-model). Details for each field are described in the [specification](#specification). | Required | + + + +## Configuration model + +The following outline shows how to format the configurations in the `Gateway` object. Click on a property name to view details about the configuration. + +* [`gatewayClassName`](#gatewayclassname): string | required +* [`listeners`](#listeners): array of objects | required + * [`allowedRoutes`](#listeners-allowedroutes): object | required + * [`namespaces`](#listeners-allowedroutes-namespaces): object | required + * [`from`](#listeners-namespaces-from): string | required + * [`selector`](#listeners-allowedroutes-namespaces-selector): object | required if `from` is configured to `selector` + * [`matchExpressions`](#listeners-allowedroutes-namespaces-selector-matchexpressions): array of objects | required if `matchLabels` is not configured + * [`key`](#listeners-allowedroutes-namespaces-selector-matchexpressions): string | required if `matchExpressions` is declared + * [`operator`](#listeners-allowedroutes-namespaces-selector-matchexpressions): string | required if `matchExpressions` is declared + * [`values`](#listeners-allowedroutes-namespaces-selector-matchexpressions): array of strings | required if `matchExpressions` is declared + * [`matchLabels`](#listeners-allowedroutes-namespaces-selector-matchlabels): map of strings | required if `matchExpressions` is not configured + * [`hostname`](#listeners-hostname): string | required + * [`name`](#listeners-name): string | required + * [`port`](#listeners-port): integer | required + * [`protocol`](#listeners-protocol): string | required + * [`tls`](#listeners-tls): object | required if `protocol` is set to `HTTPS` + * [`certificateRefs`](#listeners-tls): array or objects | required if `tls` is declared + * [`name`](#listeners-tls): string | required if `certificateRefs` is declared + * [`namespace`](#listeners-tls): string | required if `certificateRefs` is declared + * [`mode`](#listeners-tls): string | required if `certificateRefs` is declared + * [`options`](#listeners-tls): map of strings | optional + +## Specification + +This topic provides details about the configuration parameters. + +### gatewayClassName +Specifies the name of the [`GatewayClass`](/docs/api-gateway/configuration/gatewayclass) resource used for the `Gateway` instance. Unless you are using a custom [GatewayClass](/docs/api-gateway/configuration/gatewayclass), this value should be set to `consul-api-gateway`. +* Type: string +* Required: required + +### listeners +Specifies the `listeners` associated with the `Gateway`. At least one `listener` must be specified. Each `listener` within a `Gateway` must have a unique combination of `hostname`, `port`, and `protocol`. +* Type: array of objects +* Required: required + +### listeners.allowedRoutes +Specifies a `namespace` object that defines the types of routes that may be attached to a listener. +* Type: object +* Required: required + +### listeners.allowedRoutes.namespaces +Determines which routes are allowed to attach to the `listener`. Only routes in the same namespace as the `Gateway` may be attached by default. +* Type: string +* Required: optional +* Default: Same namespace as the parent Gateway + +### listeners.allowedRoutes.namespaces.from +Determines which namespaces are allowed to attach a route to the `Gateway`. You can specify one of the following strings: + +* `All`: Routes in all namespaces may be attached to the `Gateway`. +* `Same` (default): Only routes in the same namespace as the `Gateway` may be attached. +* `Selector`: Only routes in namespaces that match the [`selector`](#listeners-allowedroutes-namespaces-selector) may be attached. + +This parameter is required. + +### listeners.allowedRoutes.namespaces.selector +Specifies a method for selecting routes that are allowed to attach to the listener. The `Gateway` checks for namespaces in the network that match either a regular expression or a label. Routes from the matching namespace are allowed to attach to the listener. + +You can configure one of the following objects: + +* [`matchExpressions`](#listeners-allowedroutes-namespaces-selector-matchexpressions) +* [`matchLabels`](#listeners-allowedroutes-namespaces-selector-matchlabels) + +This field is required when [`from`](#listeners-allowedroutes-namespaces-from) is configured to `Selector`. + +### listeners.allowedRoutes.namespaces.selector.matchExpressions +Specifies an array of requirements for matching namespaces. If a match is found, then routes from the matching namespace(s) are allowed to attach to the `Gateway`. The following table describes members of the `matchExpressions` array: + +| Requirement | Description | Type | Required | +|--- |--- |--- |--- | +|`key` | Specifies the label that the `key` applies to. | string | required when `matchExpressions` is declared | +|`operator` | Specifies the key's relation to a set of values. You can use the following keywords: | string | required when `matchExpressions` is declared | +|`values` | Specifies an array of string values. If `operator` is configured to `In` or `NotIn`, then the `values` array must contain values. If `operator` is configured to `Exists` or `DoesNotExist`, then the `values` array must be empty. | array of strings | required when `matchExpressions` is declared | + +In the following example, routes in namespaces that contain `foo` and `bar` are allowed to attach routes to the `Gateway`. +```yaml +namespaceSelector: + matchExpressions: + - key: kubernetes.io/metadata.name + operator: In + values: + - foo + - bar +``` + +Refer to [Labels and Selectors](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#resources-that-support-set-based-requirements) in the Kubernetes documentation for additional information about `matchExpressions`. + +### listeners.allowedRoutes.namespaces.selector.matchLabels +Specifies an array of labels and label values. If a match is found, then routes with the matching label(s) are allowed to attach to the `Gateway`. This selector can contain any arbitrary key/value pair. + +In the following example, routes in namespaces that have a `bar` label are allowed to attach to the `Gateway`. + +```yaml +namespaceSelector: + matchLabels: + foo: bar +``` + +Refer to [Labels and Selectors](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) in the Kubernetes documentation for additional information about labels. + +### listeners.hostname +Specifies the `listener`'s hostname. +* Type: string +* Required: required + +### listeners.name +Specifies the `listener`'s name. +* Type: string +* Required: required + +### listeners.port +Specifies the port number that the `listener` attaches to. +* Type: integer +* Required: required + +### listeners.protocol +Specifies the protocol the `listener` communicates on. +* Type: string +* Required: required + +Allowed values are `TCP`, `HTTP`, or `HTTPS` + +### listeners.tls +Specifies the `tls` configurations for the `Gateway`. The `tls` object is required if `protocol` is set to `HTTPS`. The object contains the following fields: + +| Parameter | Description | Type | Required | +| --- | --- | --- | --- | +| `certificateRefs` |
Specifies Kubernetes `name` and `namespace` objects that contains TLS certificates and private keys.
The certificates establish a TLS handshake for requests that match the `hostname` of the associated `listener`. Each reference must be a Kubernetes Secret. If you are using a Secret in a namespace other than the `Gateway`'s, each reference must also have a corresponding [`ReferencePolicy`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.ReferencePolicy).
| Object or array | Required if `tls` is set | +| `mode` | Specifies the TLS Mode. Should always be set to `Terminate` for `HTTPRoutes` | string | Required if `certificateRefs` is set | +| `options` | Specifies additional Consul API Gateway options. | Map of strings | optional | + +The following keys for `options` are available +* `api-gateway.consul.hashicorp.com/tls_min_version` +* `api-gateway.consul.hashicorp.com/tls_max_version` +* `api-gateway.consul.hashicorp.com/tls_cipher_suites` + +In the following example, `tls` settings are configured to use a secret named `consul-server-cert` in the same namespace as the `Gateway` and the minimum tls version is set to `TLSv1_2`. + +```yaml + +tls: + certificateRefs: + name: consul-server-cert + group: "" + kind: Secret + mode: Terminate + options: + api-gateway.consul.hashicorp.com/tls_min_version: "TLSv1_2" + +``` + diff --git a/website/content/docs/api-gateway/configuration/gatewayclass.mdx b/website/content/docs/api-gateway/configuration/gatewayclass.mdx new file mode 100644 index 000000000000..70684e73080c --- /dev/null +++ b/website/content/docs/api-gateway/configuration/gatewayclass.mdx @@ -0,0 +1,81 @@ +--- +layout: docs +page_title: Consul API Gateway GatewayClass +description: >- + Consul API Gateway GatewayClass +--- + +# GatewayClass + +This topic provides describes how to configure the `GatewayClass` resource, a generic Kubernetes gateway object used as a template for creating `Gateway` resources. + +## Introduction + +The `GatewayClass` 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. + +The `GatewayClass` resource is a generic Kubernetes gateway object. For configuration specific to Consul API Gateway, see [GatewayClassConfig](/docs/api-gateway/configuration/gatewayclassconfig). + +## Configuration model +The following outline shows how to format the configurations in the `GatewayClass` object. Click on a property name to view details about the configuration. + +* [`controllerName`](#controllername): string | required +* [`parametersRef`](#parametersref): object | optional + * [`group`](#parametersref): string | required if `parametersRef` is set + * [`kind`](#parametersref): string | required if `parametersRef` is set + * [`name`](#parametersref): string | required if `parametersRef` is set +* [`description`](#description): string | optional + +## Specification + +This topic provides details about the configuration parameters. + +### controllerName +Specifies the name of the controller that manages the gateways generated by this class. +The value must always be `hashicorp.com/consul-api-gateway-controller`. + +* Type: string +* Required: required + +### parametersRef +Defines an API object that references additional configurations required by the gateway controller. The following table describes the fields that you must include in the `parametersRef` configuration. + +* Type: object +* Required: optional + +| Parameter | Description | Type | Required | +| --- | --- | --- | --- | +| `group` | Specifies the Kubernetes group that the `parametersRef` is a member of.
The value must always be `api-gateway.consul.hashicorp.com`.
The `parametersRef.group` is always the same across all deployments of Consul API Gateway. | String | Required | +| `kind` | Specifies the type of Kubernetes object that the `parametersRef` configuration defines.
The value must always be `GatewayClassConfig`.
This `parametersRef.kind` is always the same across all deployments of Consul API Gateway. | String | Required | +| `name` | Specfies a name for the `GatewayClassConfig` object. | String | Required | + + +### description +Specifies a human-readable description of the gateway class. We recommend using the description field to describe the gateway class's purpose. + +* Type: string +* Required: optional + +## Example Configuration +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 + description: The gateway class is for creating test gateways class configurations +``` + + +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. + diff --git a/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx b/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx new file mode 100644 index 000000000000..58f7af80d495 --- /dev/null +++ b/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx @@ -0,0 +1,201 @@ +--- +layout: docs +page_title: Consul API Gateway GatewayClassConfig +description: >- + Consul API Gateway GatewayClassConfig +--- + +# GatewayClassConfig + +This topic provides full details about the `GatewayClassConfig` resource. + +## Introduction + +The `GatewayClassConfig` object contains Consul API Gateway-related configuration parameters. Apply the parameters by adding the [`GatewayClass`](#gatewayclass) object to your Kubernetes values file and specifying the name of the `GatewayClassConfig`. + +## Configuration model + +The following outline shows how to format the configurations in the `GatewayClassConfig` object. Click on a property name to view details about the configuration. + +* [`consul`](#consul): object | optional + * [`address`](#consul-address): string | optional + * [`authentication`](#consul-authentication): object | optional + * [`account`]([#consul-authentication-account): string | optional + * [`managed`](#consul-authentication-managed): bool | optional + * [`method`](#consul-authentication-method): string | optional + * [`namespace`](#consul-authentication-namespace): string | optional + * [`ports`](#consul-ports): object | optional + * [`grpc`](#consul-ports-grpc): integer | optional + * [`http`](#consul-ports-http): integer | optional + * [`scheme`](#consul-scheme): string | optional +* [`copyAnnotations`](#copyAnnotations): object | optional + * [`service`](#copyAnnotations-service): array of strings | optional +* [`deployment`](#deployment): object | optional + * [`defaultInstances`](#deployment-defaultinstances): integer | optional + * [`maxInstances`](#deployment-maxinstances): integer | optional + * [`minInstances`](#deployment-mininstances): integer | optional +* [`image`](#image): object | optional + * [`consulAPIGateway`](#image-consulapigateway): string | optional + * [`envoy`](#image-envoy): string | optional +* [`logLevel`](#loglevel): string | optional +* [`nodeSelector`](#nodeselector): string | optional +* [`serviceType`](#servicetype): string | optional +* [`useHostPorts`](#usehostports): boolean | optional + +## Specification + +This topic provides details about the configuration parameters. + +### consul +Specifies configurations that enable an instance of Consul API Gateway to interact with Consul. +* Type: object +* Required: optional + +### consul.address +Specifies the address of the Consul server that the `Gateway` communicates with in the gateway pod. If unspecified, the pod attempts to use a local agent on the host where the pod is running. +* Type: string +* Required: optional +* Default: local agent + +### consul.authentication.account +Specifies the [Kubernetes service account](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) to use for authentication. +* Type: string +* Required: optional + +### 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. +* Type: boolean +* Required: optional +* Default: `false` + +### consul.authentication.method +Specifies the [Consul auth method](/docs/security/acl/auth-methods) used for initial authentication by Consul API Gateway. +* Type: string +* Required: optional + +### consul.authentication.namespace +Specifies the Consul namespace to use for authentication. +* Type: string +* Required: optional + +### consul.ports.grpc +Specifies the gRPC port for Consul's xDS server. +* Type: integer +* Required: optional +* Default: `8502` + +### consul.ports.http +Specifies the Consul HTTP port to use for authentication. +* Type: integer +* Required: optional +* Default: `8500` + +### consul.scheme +Specifies the scheme to use for connecting to Consul. +* Type: string +* Required: optional +* Default: `http` + +You can specify the following strings: +* `http` +* `https` + +### copyAnnotations.service +Specifies an array of Kubernetes [annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) to copy to the gateway service. +* Type: Array of strings +* Required: optional + +### deployment.defaultInstances +Specifies the number of gateway instances to deploy per gateway configuration. +* Type: Integer +* Required: optional +* Default: `1` + +### deployment.maxInstances +Specifies the maximum allowed number of gateway instances per gateway configuration. +* Type: Integer +* Required: optional +* Default: `8` + +### deployment.minInstances +Specifies the minimum allowed number of gateway instances per gateway configuration. +* Type: Integer +* Required: optional +* Default: `1` + +### image.consulAPIGateway +Specifies the Docker image to use for the `consul-api-gateway` container. View available image tags on [DockerHub](https://hub.docker.com/r/hashicorp/consul-api-gateway/tags). + +The default value is suitable for most deployments, but you may require a specific version of the Consul API Gateway depending on your environment. +* Type: string +* Required: optional +* Default: `"hashicorp/consul-api-gateway:RELEASE_VERSION"` + +### image.envoy +Specifies the Docker image to use for the Envoy proxy container. View available image tags on [DockerHub](https://hub.docker.com/r/hashicorp/consul-api-gateway/tags). + +The default value is suitable for most deployments, but you may require a specific version of Envoy depending on your environment. +* Type: string +* Required: optional +* Default: `"envoyproxy/envoy:RELEASE_VERSION"` + +### logLevel +Specifies the error reporting level for logs. +* Type: string +* Required: optional +* Default: `info` + +You can specify the following strings: +* `error` +* `warning` +* `info` +* `debug` +* `trace` + +### nodeSelector +Pods normally run on multiple nodes. You can specify a set of parameters in the `nodeSelector` that constrain the nodes on which the pod can run, enabling 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. + +* Type: string +* Required: optional + +### serviceType +Specifies the ingress methods for the gateway's Kubernetes service. +* Type: string +* Required: optional + +You can specify the following strings: +* `ClusterIP`: The gateway is only accessible from inside the cluster. +* `NodePort`: The gateway is exposed on each Kubernetes node at a static port. +* `LoadBalancer`: The gateway is exposed to external traffic by a load balancer. + +For more on Kubernetes services, see [Publishing Services](https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types). + +### useHostPorts +If set to `true`, then the Envoy container ports are mapped to host ports. +* Type: boolean +* Required: optional +* Default: `false` + + +## 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` : + + + + ```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 +``` + + +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. diff --git a/website/content/docs/api-gateway/configuration/index.mdx b/website/content/docs/api-gateway/configuration/index.mdx new file mode 100644 index 000000000000..630f26ab932d --- /dev/null +++ b/website/content/docs/api-gateway/configuration/index.mdx @@ -0,0 +1,23 @@ +--- +layout: docs +page_title: Consul API Gateway Configuration +description: >- + Consul API Gateway Configuration +--- + +# Configuration + +This topic provides an overview of the configuration items that enable Consul API Gateway to manage traffic into your Consul service mesh. + +- [Gateway](/docs/api-gateway/configuration/gateway) defines the main infrastructure resource that links API gateway components. It specifies the name of the `GatewayClass` and one or more [listeners](/docs/api-gateway/configuration/gateway#listeners), which specify the logical endpoints bound to the gateway's addresses. +- [GatewayClass](/docs/api-gateway/configuration/gatewayclass) defines a class of gateway resources that you can use as a template for creating gateways. +- [GatewayClassConfig](/docs/api-gateway/configuration/gatewayclassconfig) describes additional Consul API Gateway-related configuration parameters for the GatewayClass resource. +- [Routes](/docs/api-gateway/configuration/routes) specifies the path from the gateway to the backend service(s) client to the listener. + +You can create a basic Gateway object using the default [`gatewayClassName`](/docs/api-gateway/configuration/gateway#gatewayclassname) (`consul-api-gateway`). If you want to create custom Gateways suitable for your environment, complete the following steps: + +1. Define a [GatewayClassConfig](/docs/api-gateway/configuration/gatewayclassconfig) that contains your custom configurations. +1. Define a [GatewayClass](/docs/api-gateway/configuration/gatewayclass) and configure the [`parametersRef.name`](/docs/api-gateway/configuration/gatewayclass#parametersref-name) to reference the name of your [GatewayClassConfig](/docs/api-gateway/configuration/gatewayclassconfig). +1. Define a [Gateway](/docs/api-gateway/configuration/gateway) and configure the [`gatewayClassName`](/docs/api-gateway/configuration/gateway#gatewayclassname) to reference the name of your [GatewayClass](/docs/api-gateway/configuration/gatewayclass). + + diff --git a/website/content/docs/api-gateway/configuration/routes.mdx b/website/content/docs/api-gateway/configuration/routes.mdx new file mode 100644 index 000000000000..7819d482f6bf --- /dev/null +++ b/website/content/docs/api-gateway/configuration/routes.mdx @@ -0,0 +1,89 @@ +--- +layout: docs +page_title: Consul API Gateway Routes +description: >- + Consul API Gateway Routes +--- + +# 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 + ``` + + + +To create a route for a `backendRef` in a different namespace, you must also +create a [ReferencePolicy](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.ReferencePolicy). + +The following example creates a route named `example-route` in namespace `gateway-namespace`. This route has a `backendRef` in namespace `service-namespace`. Traffic is allowed because the `ReferencePolicy`, named `reference-policy` in namespace `service-namespace`, allows traffic from `HTTPRoutes` in `gateway-namespace` to `Services` in `service-namespace`. + + + + ```yaml + apiVersion: gateway.networking.k8s.io/v1alpha2 + kind: HTTPRoute + metadata: + name: example-route + namespace: gateway-namespace + spec: + parentRefs: + - name: example-gateway + rules: + - backendRefs: + - kind: Service + name: echo + namespace: service-namespace + port: 8080 + --- + + apiVersion: gateway.networking.k8s.io/v1alpha2 + kind: ReferencePolicy + metadata: + name: reference-policy + namespace: service-namespace + spec: + from: + - group: gateway.networking.k8s.io + kind: HTTPRoute + namespace: gateway-namespace + to: + - group: "" + kind: Service + name: echo + ``` + + + +## MeshService + +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 | +| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------- | +| `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/consul-api-gateway-install.mdx b/website/content/docs/api-gateway/consul-api-gateway-install.mdx deleted file mode 100644 index a72c5ae5d2ee..000000000000 --- a/website/content/docs/api-gateway/consul-api-gateway-install.mdx +++ /dev/null @@ -1,431 +0,0 @@ ---- -layout: docs -page_title: Consul API Gateway Install -description: >- - Installing Consul API Gateway ---- - -# Installing Consul API Gateway - -This topic describes how to use the Consul API Gateway add-on module. It includes instructions for installation and configuration. - -## Requirements - -Ensure that the environment you are deploying Consul API Gateway in meets the requirements listed in the [Technical Specifications][tech-specs]. This includes validating that the requirements for minimum versions of software are met. See the [Release Notes][rel-notes] for the version of API Gateway you are deploying. - -## Installation - -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 - ``` - -1. Issue the following command to install the CRDs: - - ```shell-session - $ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?ref=v$VERSION" - ``` - -1. Create a `values.yaml` file for your Consul API Gateway deployment by copying the following content and running it in the environment where you set the `VERSION` environment variable. The Consul Helm chart uses this `values.yaml` file to deploy the API Gateway. Available versions of the [Consul](https://hub.docker.com/r/hashicorp/consul/tags) and [Consul API Gateway](https://hub.docker.com/r/hashicorp/consul-api-gateway/tags) Docker images can be found on DockerHub, with additional context on version compatibility published in [GitHub releases](https://github.com/hashicorp/consul-api-gateway/releases). For more options to configure your Consul API Gateway deployment through the Helm chart, refer to [Helm Chart Configuration - apiGateway](https://www.consul.io/docs/k8s/helm#apigateway). - - - - ```shell - cat < values.yaml - global: - name: consul - connectInject: - enabled: true - controller: - enabled: true - apiGateway: - enabled: true - image: hashicorp/consul-api-gateway:$VERSION - EOF - ``` - - - -1. Install Consul API Gateway using the standard Consul Helm chart and specify the custom values file. Available versions of the [Consul Helm chart](https://github.com/hashicorp/consul-k8s/releases) can be found in GitHub releases. - - ```shell-session - $ helm install consul hashicorp/consul --version 0.45.0 --values values.yaml --create-namespace --namespace consul - ``` - -## 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). - - - - ```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. - --> **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 - -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 configuration 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"]` | -| `deployment.defaultInstances` | Specifies the number of instances to deploy by default for each gateway. | Integer | 1 | -| `deployment.maxInstances` | Specifies the maximum allowed number of instances per gateway. | Integer | 8 | -| `deployment.minInstances` | Specifies the minimum allowed number of instances per gateway. | Integer | 1 | -| `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 -``` - - - -If you configure a listener's `certificateRefs` to reference a secret in a different namespace, you must also create a [ReferencePolicy](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.ReferencePolicy) in the same namespace as the secret. The `ReferencePolicy` grants the listener the permission to read the secret. - -The following example creates a `Gateway` named `example-gateway` in `gateway-namespace`. This `Gateway` has a `certificateRef` in `secret-namespace`. -The listener can use the certificate because `reference-policy` in `secret-namespace` is configured to allow `Gateways` in `gateway-namespace` to reference `Secrets` in `secret-namespace`. - - - -```yaml -apiVersion: gateway.networking.k8s.io/v1alpha2 -kind: Gateway -metadata: - name: example-gateway - namespace: gateway-namespace - 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 - namespace: secret-namespace ---- - -apiVersion: gateway.networking.k8s.io/v1alpha2 -kind: ReferencePolicy -metadata: - name: reference-policy - namespace: secret-namespace -spec: - from: - - group: gateway.networking.k8s.io - kind: Gateway - namespace: gateway-namespace - to: - - group: "" - kind: Secret - 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 further 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. - -#### Scaling - -You can scale a logical gateway object to multiple instances with the [`kubectl scale`](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#scaling-a-deployment) command. The object scales according to the bounds set in `GatewayClassConfig`. - -```shell-session -$ kubectl get deployment --selector api-gateway.consul.hashicorp.com/name=example-gateway -NAME READY UP-TO-DATE AVAILABLE -example-gateway 1/1 1 1 -``` -```shell-session -$ kubectl scale deployment/example-gateway --replicas=3 -deployment.apps/example-gateway scaled -``` -```shell-session -$ kubectl get deployment --selector api-gateway.consul.hashicorp.com/name=example-gateway -NAME READY UP-TO-DATE AVAILABLE -example-gateway 3/3 3 3 -``` - -### 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 -``` - - - -To create a route for a `backendRef` in a different namespace, you must also -create a [ReferencePolicy](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.ReferencePolicy). - -The following example creates a route named `example-route` in namespace `gateway-namespace`. This route has a `backendRef` in namespace `service-namespace`. Traffic is allowed because the `ReferencePolicy`, named `reference-policy` in namespace `service-namespace`, allows traffic from `HTTPRoutes` in `gateway-namespace` to `Services` in `service-namespace`. - - - -```yaml -apiVersion: gateway.networking.k8s.io/v1alpha2 -kind: HTTPRoute -metadata: - name: example-route - namespace: gateway-namespace -spec: - parentRefs: - - name: example-gateway - rules: - - backendRefs: - - kind: Service - name: echo - namespace: service-namespace - port: 8080 ---- - -apiVersion: gateway.networking.k8s.io/v1alpha2 -kind: ReferencePolicy -metadata: - name: reference-policy - namespace: service-namespace -spec: - from: - - group: gateway.networking.k8s.io - kind: HTTPRoute - namespace: gateway-namespace - to: - - group: "" - kind: Service - name: echo -``` - - - -### MeshService - -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 | -| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------- | -| `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. - - -[tech-specs]: /docs/api-gateway/tech-specs -[rel-notes]: /docs/release-notes diff --git a/website/content/docs/api-gateway/index.mdx b/website/content/docs/api-gateway/index.mdx index 5a6c75af4091..2c32c5abdd76 100644 --- a/website/content/docs/api-gateway/index.mdx +++ b/website/content/docs/api-gateway/index.mdx @@ -18,7 +18,7 @@ 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). -## Implementation +## How Does Consul API Gateway Work? Consul API Gateway can be deployed on Kubernetes-based runtime environments and requires that Consul service mesh be deployed on the Kubernetes cluster. diff --git a/website/content/docs/api-gateway/install.mdx b/website/content/docs/api-gateway/install.mdx new file mode 100644 index 000000000000..3d1a542ee8ba --- /dev/null +++ b/website/content/docs/api-gateway/install.mdx @@ -0,0 +1,89 @@ +--- +layout: docs +page_title: Install Consul API Gateway +description: >- + Installing Consul API Gateway +--- + +# Install Consul API Gateway + +This topic describes how to install and configure Consul API Gateway. + +## Requirements + +Ensure that the environment you are deploying Consul API Gateway in meets the requirements listed in the [Technical Specifications][tech-specs]. This includes validating that the requirements for minimum versions of software are met. Refer to the [Release Notes][rel-notes] for the version of API Gateway you are deploying. + +## Installation + +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 + ``` + +1. Issue the following command to install the CRDs: + + ```shell-session + $ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?ref=v$VERSION" + ``` + +1. Create a `values.yaml` file for your Consul API Gateway deployment by copying the following content and running it in the environment where you set the `VERSION` environment variable. The Consul Helm chart uses this `values.yaml` file to deploy the API Gateway. Available versions of the [Consul](https://hub.docker.com/r/hashicorp/consul/tags) and [Consul API Gateway](https://hub.docker.com/r/hashicorp/consul-api-gateway/tags) Docker images can be found on DockerHub, with additional context on version compatibility published in [GitHub releases](https://github.com/hashicorp/consul-api-gateway/releases). For more options to configure your Consul API Gateway deployment through the Helm chart, refer to [Helm Chart Configuration - apiGateway](https://www.consul.io/docs/k8s/helm#apigateway). + + + + ```shell + cat < values.yaml + global: + name: consul + connectInject: + enabled: true + controller: + enabled: true + apiGateway: + enabled: true + image: hashicorp/consul-api-gateway:$VERSION + EOF + ``` + + +1. Install Consul API Gateway using the standard Consul Helm chart or Consul K8s CLI specify the custom values file. Available versions of the [Consul Helm chart](https://github.com/hashicorp/consul-k8s/releases) can be found in GitHub releases. + + + + + ~> **Note:** Refer to the official [Consul K8S CLI documentation](https://www.consul.io/docs/k8s/k8s-cli) to find additional settings. + + ```shell-session + $ brew tap hashicorp/tap + ``` + + ```shell-session + $ brew install hashicorp/tap/consul-k8s + ``` + + ```shell-session + $ consul-k8s install -config-file=values.yaml -set global.image=hashicorp/consul:1.12.2 + ``` + + + + + Add the HashiCorp Helm repository. + + ```shell-session + $ helm repo add hashicorp https://helm.releases.hashicorp.com + ``` + 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 + ``` + + + + +[tech-specs]: /docs/api-gateway/tech-specs +[rel-notes]: /docs/release-notes diff --git a/website/content/docs/api-gateway/upgrade-specific-versions.mdx b/website/content/docs/api-gateway/upgrades.mdx similarity index 100% rename from website/content/docs/api-gateway/upgrade-specific-versions.mdx rename to website/content/docs/api-gateway/upgrades.mdx diff --git a/website/content/docs/api-gateway/usage.mdx b/website/content/docs/api-gateway/usage.mdx new file mode 100644 index 000000000000..e89c0556fca8 --- /dev/null +++ b/website/content/docs/api-gateway/usage.mdx @@ -0,0 +1,135 @@ +--- +layout: docs +page_title: Consul API Gateway Basic Usage +description: >- + Consul API Gateway Basic Usage +--- + + +# Basic Usage + +This topic describes the basic workflow for implementing Consul API Gateway configurations. + +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 (see [Installation](/docs/api-gateway/consul-api-gateway-install)). +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. + + + + ```yaml + apiGateway: + enabled: true + managedGatewayClass: + ``` + + + +1. Issue the `kubectl apply` command to implement the configurations, e.g.: + + ```shell-session + $ kubectl apply -f gateway.yaml routes.yaml + ``` + + + +## 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/data/docs-nav-data.json b/website/data/docs-nav-data.json index ae5624a0d981..4bb776ddee22 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -355,19 +355,44 @@ }, { "title": "Installation", - "path": "api-gateway/consul-api-gateway-install" + "path": "api-gateway/install" }, { "title": "Technical Specifications", "path": "api-gateway/tech-specs" }, { - "title": "Common Errors", - "path": "api-gateway/common-errors" + "title": "Upgrades", + "path": "api-gateway/upgrades" }, { - "title": "Upgrades", - "path": "api-gateway/upgrade-specific-versions" + "title": "Usage", + "path": "api-gateway/usage" + }, + { + "title": "Configuration", + "routes": [ + { + "title": "Overview", + "path": "api-gateway/configuration" + }, + { + "title": "Gateway", + "path": "api-gateway/configuration/gateway" + }, + { + "title": "GatewayClass", + "path": "api-gateway/configuration/gatewayclass" + }, + { + "title": "GatewayClassConfig", + "path": "api-gateway/configuration/gatewayclassconfig" + }, + { + "title": "Routes", + "path": "api-gateway/configuration/routes" + } + ] } ] }, diff --git a/website/redirects.js b/website/redirects.js index 76d18f6523ac..52a313b046c0 100644 --- a/website/redirects.js +++ b/website/redirects.js @@ -1273,4 +1273,14 @@ module.exports = [ destination: '/docs/k8s/installation/vault/data-integration/connect-ca', permanent: true, }, + { + source: '/docs/api-gateway/common-errors', + destination: '/docs/api-gateway/usage#error-messages', + permanent: true, + }, + { + source: '/docs/api-gateway/upgrade-specific-versions', + destination: '/docs/api-gateway/upgrades', + permanent: true, + }, ]