--- layout: docs page_title: Consul API Gateway Usage description: >- Using Consul API gateway functionality --- # Consul API Gateway Usage This topic describes how to use the Consul API Gateway add-on module. It includes instructions for installation and configuration. ## Requirements Refer to [Technical Specifications](/docs/api-gateway/tech-specs) for minimum software requirements. ## Installation 1. Issue the following command to install the CRDs: ```shell-session $ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?ref=v0.1.0" ``` 1. Create a `values.yaml` file for your Consul API Gateway deployment. Copy the content below into the `values.yaml` file. The `values.yaml` will be used by the Consul Helm chart. See [Helm Chart Configuration - apigateway](https://www.consul.io/docs/k8s/helm#apigateway) for more available options on how to configure your Consul API Gateway deployment via the Helm chart. ```yaml global: name: consul image: 'hashicorp/consul:1.11.2' connectInject: enabled: true controller: enabled: true apiGateway: enabled: true image: hashicorp/consul-api-gateway:0.1.0 ``` 1. Install Consul API Gateway using the standard Consul Helm chart and specify the custom values file. ```shell-session $ helm install consul hashicorp/consul --version 0.41.0 --values values.yaml ``` ## Usage 1. Verify that the [requirements](#requirements) have been met. 1. Verify that the Consul API Gateway CRDs and controller have been installed and applied (see [Installation](#installation)). 1. Configure the artifacts described below in [Configuration](#configuration). If the following config is added to the `values.yaml` Helm config, the GatewayClassConfig and GatewayClass will be created automatically, and only the Gateway, Listeners and Routes will need to be configured manually. The [`serviceType`](https://www.consul.io/docs/k8s/helm#v-apigateway-managedgatewayclass-servicetype) for a managed GatewayClass will default to `LoadBalancer`, which is appropriate for most deployments to managed Kubernetes cloud offerings (EKS, GKE, AKS) - other deployments, such as to a [kind](https://kind.sigs.k8s.io/) cluster, may require specifying `NodePort` or `ClusterIP` instead. ```yaml apiGateway: managedGatewayClass: enabled: true ``` 1. Issue the `kubectl apply` command to implement the configurations, e.g.: ```shell-session $ kubectl apply -f gateway.yaml routes.yaml ``` ## Configuration Configure the following artifacts to facilitate ingress into your Consul service mesh: - [GatewayClassConfig](#gatewayclassconfig): Describes additional Consul API Gateway-related configuration parameters for the `GatewayClass` resource. - [GatewayClass](#gatewayclass): Defines a class of gateway resources that you can use as a template for creating gateways. - [Gateway](#gateway): Defines the main infrastructure resource that links API gateway components. It specifies the name of the `GatewayClass` and one or more `listeners` (see [Listeners](#listeners)), which specify the logical endpoints bound to the gateway's addresses. - [Routes](#routes): Specifies the path from the client to the listener. ### GatewayClassConfig The `GatewayClassConfig` object describes Consul API Gateway-related configuration parameters for the [`GatewayClass`](#gatewayclass). Add the `kind: GatewayClassConfig` option to the gateway values file to declare a gateway class. The following example creates a gateway class config called `test-gateway-class-config`: ```yaml apiVersion: api-gateway.consul.hashicorp.com/v1alpha1 kind: GatewayClassConfig metadata: name: test-gateway-class-config spec: useHostPorts: true logLevel: 'trace' consul: scheme: 'https' ports: http: 8501 grpc: 8502 ``` The following table describes the allowed parameters for the `spec` array: | Parameter | Description | Type | Default | | --- | --- | ---- | ------- | | `consul.address` | Specifies the address of the Consul server to communicate with in the gateway pod. If unspecified, the pod will attempt to use a local agent on the host on which the pod is running. | String | N/A | | `consul.authentication.account` | Specifies the Kubernetes service account to use for authentication. | String | N/A | | `consul.authentication.managed` | Set to `true` to enable deployments to run with managed service accounts created by the gateway controller. The `consul.authentication.account` field is ignored when this option is enabled. | Boolean | `false` | | `consul.authentication.method` | Specifies the Consul auth method used for initial authentication by Consul API Gateway. | String | N/A | | `consul.authentication.namespace` | Specifies the Consul namespace to use for authentication. | String | N/A | | `consul.ports.grpc` | Specifies the gRPC port for Consul's xDS server. | Integer | `8502` | | `consul.ports.http` | Specifies the port for Consul's HTTP server. | Integer | `8500` | | `consul.scheme` | Specifies the scheme to use for connecting to Consul. The supported values are `"http"` and `"https"`. | String | `"http"` | | `copyAnnotations.service` | List of annotations to copy to the gateway service. | Array | `["external-dns.alpha.kubernetes.io/hostname"]` | | `image.consulAPIGateway` | The image to use for consul-api-gateway. View available image tags on [DockerHub](https://hub.docker.com/r/hashicorp/consul-api-gateway/tags). | String | `"hashicorp/consul-api-gateway:RELEASE_VERSION"` | | `image.envoy` | Specifies the container image to use for Envoy. View available image tags on [DockerHub](https://hub.docker.com/r/envoyproxy/envoy/tags). | String | `"envoyproxy/envoy:RELEASE_VERSION"` | | `logLevel` | Specifies the error reporting level for logs. You can specify the following values: `error`, `warning`, `info`, `debug`, `trace`. | String | `"info"` | | `nodeSelector` | Specifies a set of parameters that constrain the nodes on which the pod can run. Defining nodes with the `nodeSelector` enables the pod to fit on a node. The selector must match a node's labels for the pod to be scheduled on that node. Refer to the [Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/) for additional information. | Object | N/A | | `serviceType` | Specifies the ingress methods for a service. The following values are supported:
`ClusterIP`
`NodePort`
`LoadBalancer`. | String | N/A | | `useHostPorts` | If set to `true`, then the Envoy container ports are mapped to host ports. | Boolean | `false` | Refer to the [Consul API Gateway repository](https://github.com/hashicorp/consul-api-gateway/blob/main/config/crd/bases/api-gateway.consul.hashicorp.com_gatewayclassconfigs.yaml) for the complete specification. ### GatewayClass The `GatewayClass` resource is used as a template for creating `Gateway` resources. The specification includes the name of the controller (`controllerName`) and an API object containing controller-specific configuration resources within the cluster (`parametersRef`). The value of the `controllerName` field must be set to `hashicorp.com/consul-api-gateway-controller`. When gateways are created from a `GatewayClass`, they use the parameters specified in the `GatewayClass` at the time of instantiation. Add the `kind: GatewayClass` option to the the gateway values file to declare a gateway class. The following example creates a gateway class called `test-gateway-class`: ```yaml apiVersion: gateway.networking.k8s.io/v1alpha2 kind: GatewayClass metadata: name: test-gateway-class spec: controllerName: 'hashicorp.com/consul-api-gateway-controller' parametersRef: group: api-gateway.consul.hashicorp.com kind: GatewayClassConfig name: test-gateway-class-config ``` Refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.GatewayClass) for details about configuring gateway classes. ### Gateway The gateway configuration is the main infrastructure resource that links API gateway components. It specifies the name of the `GatewayClass` and one or more `listeners`. Add the `kind: Gateway` option to the configuration file to declare a gateway. The following example creates a gateway called `example-gateway`. The gateway is based on the `test-gateway-class` and includes a listener called `https` (see [Listeners](#listeners) for details about the `listener` configuration). ```yaml apiVersion: gateway.networking.k8s.io/v1alpha2 kind: Gateway metadata: name: example-gateway annotations: 'external-dns.alpha.kubernetes.io/hostname': DNS_HOSTNAME spec: gatewayClassName: test-gateway-class listeners: - protocol: HTTPS hostname: DNS_HOSTNAME port: 443 name: https allowedRoutes: namespaces: from: Same tls: certificateRefs: - name: gateway-production-certificate ``` Refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.Gateway) for details about configuring gateways: #### Listeners Listeners are the logical endpoints bound to the gateway's addresses. Add the `listener` object to the `gateway` configuration and specify the following properties to define a listener: | Parameter | Description | Type | Default | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------- | | `hostname` | Specifies the virtual hostname to match for protocol types. | String | none | | `port` | Specifies the network port number. | Integer | none | | `protocol` | Specifies the network protocol expected by the listener. | String | `http` | | `tls` | Collection of parameters that specify TLS options for the listener. Refer to the [`GatewayTLSConfig`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.GatewayTLSConfig) documentation for additional information about configuring TLS. | Object | N/A | | `tls.mode` | Specifies a mode for operating Consul API Gateway listeners over TLS.
You can only specify the `Terminate` mode, which configures the TLS session between the downstream client and the gateway to terminate at the gateway.
Refer to the [`TLSModeType` documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.TLSModeType) for additional information. | String | `Terminate` | | `tls.certificateRefs` | Specifies the name of secret object used for Envoy SDS (Secret Discovery Service) to support terminating TLS. Refer to the [`[]*SecretObjectReference` documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.SecretObjectReference) for additional information. | String | N/A | | `tls.options` | Specifies key/value pairs to enable extended TLS configuration specific to an implementation. | Object | N/A | | `tls.options.tls_min_version` | Specifies the minimum TLS version supported for the listener. The following values are supported: `TLS_AUTO`, `TLSv1_0`, `TLSv1_1`, `TLSv1_2`, `TLSv1_3`. | String | `TLS 1.2` | | `tls.options.tls_max_version` | Specifies the maximum TLS version supported for the listener. The specified version must be greater than or equal to `TLSMinVersion`. The following values are supported: `TLS_AUTO`, `TLSv1_0`, `TLSv1_1`, `TLSv1_2`, `TLSv1_3`. | String | `TLS 1.3` | | `tls.options.tls_cipher_suites` | Specifies the list of TLS cipher suites to support when negotiating connections using TLS 1.2 or earlier.
If unspecified, a [more secure set of cipher suites](https://github.com/hashicorp/consul-api-gateway/blob/main/internal/common/tls.go#L3-L10) than Envoy's current [default server cipher list](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/transport_sockets/tls/v3/common.proto#envoy-v3-api-field-extensions-transport-sockets-tls-v3-tlsparameters-cipher-suites) will be used.
The full list of supported cipher suites can seen in [`internal/common/tls.go`](https://github.com/hashicorp/consul-api-gateway/blob/main/internal/common/tls.go) and is dependent on underlying support in Envoy. | String | See description | Refer to the [Kubernetes Gateway API documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.Listener) for details about configuring listeners. ### Route Routes are independent configuration objects that are associated with specific listeners. Declare a route with either `kind: HTTPRoute` or `kind: TCPRoute` and configure the route parameters in the `spec` block. Refer to the Kubernetes Gateway API documentation for each object type for details: - [HTTPRoute](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.HTTPRoute) - [TCPRoute](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.TCPRoute) The following example creates a route named `example-route` associated with a listener defined in `example-gateway`. ```yaml apiVersion: gateway.networking.k8s.io/v1alpha2 kind: HTTPRoute metadata: name: example-route spec: parentRefs: - name: example-gateway rules: - backendRefs: - kind: Service name: echo port: 8080 ``` ### MeshService MeshService holds a reference to an externally managed Consul Service Mesh service, and can be used as a `backendRef` for a [`Route`](#route). | Parameter | Description | Type | Default | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------- | | `name` | Specifies the service name for a Consul service. It is assumed this service will exist in either the `consulDestinationNamespace` or mirrored Consul namespace from where this custom resource is defined, depending on the Helm configuration. Refer to the [Consul API Gateway repository](https://github.com/hashicorp/consul-api-gateway/blob/main/config/crd/bases/api-gateway.consul.hashicorp.com_meshservices.yaml) for the complete specification.