mirror of https://github.com/hashicorp/consul
155 lines
9.1 KiB
Markdown
155 lines
9.1 KiB
Markdown
---
|
|
layout: docs
|
|
page_title: API gateway for Kubernetes technical specifications
|
|
description: >-
|
|
Learn about the requirements for installing and using the Consul API gateway for Kubernetes, including required ports, component version minimums, Consul Enterprise limitations, and compatible k8s cloud environments.
|
|
---
|
|
|
|
# API gateway for Kubernetes technical specifications
|
|
|
|
This topic describes the requirements and technical specifications associated with using Consul API gateway.
|
|
|
|
## Datacenter requirements
|
|
|
|
Your datacenter must meet the following requirements prior to configuring the Consul API gateway:
|
|
|
|
- HashiCorp Consul Helm chart v1.2.0 and later
|
|
|
|
## TCP port requirements
|
|
|
|
The following table describes the TCP port requirements for each component of the API gateway.
|
|
|
|
| Port | Description | Component |
|
|
| ---- | ----------- | --------- |
|
|
| 20000 | Kubernetes readiness probe | Gateway instance pod |
|
|
| Configurable | Port for scraping Prometheus metrics. Disabled by default. | Gateway controller pod |
|
|
|
|
## OpenShift requirements
|
|
|
|
You can deploy API gateways to Kubernetes clusters managed by Red Hat OpenShift, which is a security-conscious, opinionated wrapper for Kubernetes. To enable OpenShift support, add the following parameters to your Consul values file and apply the configuration:
|
|
|
|
```yaml
|
|
openshift:
|
|
enabled: true
|
|
```
|
|
|
|
Refer to the following topics for additional information:
|
|
|
|
- [Install Consul on OpenShift clusters with Helm](/consul/docs/k8s/installation/install#install-consul-on-openshift-clusters)
|
|
- [Install Consul on OpenShift clusters with the `consul-k8s` CLI](/consul/docs/k8s/installation/install-cli#install-consul-on-openshift-clusters)
|
|
|
|
### Security context constraints
|
|
|
|
OpenShift requires a security context constraint (SCC) configuration, which restricts pods to specific groups. You can create a custom SCC or use one of the default constraints. Refer to the [OpenShift documentation](https://docs.openshift.com/container-platform/4.13/authentication/managing-security-context-constraints.html) for additional information.
|
|
|
|
By default, the SCC is set to `restricted-v2` for the `managedGatewayClass` that Consul automatically creates. The `restricted-v2` SCC is one of OpenShifts default SCCs, but you can specify a different SCC in the `openshiftSCCName` parameter:
|
|
|
|
```yaml
|
|
connectInject:
|
|
apiGateway:
|
|
managedGatewayClass:
|
|
openshiftSCCName: "restricted-v2"
|
|
```
|
|
|
|
### Privileged container ports
|
|
|
|
Containers cannot use privileged ports when OpenShift is enabled. Privileged ports are 1 through 1024, and serving applications from that range is a security risk.
|
|
|
|
To allow gateway listeners to use privileged port numbers, specify an integer value in the `mapPrivilegedContainerPorts` field of your Consul values configuration. Consul adds the value to listener port numbers that are set to a number in the privileged container range. Consul maps the configured port number to the total port number so that traffic sent to the configured port number is correctly forwarded to the service.
|
|
|
|
For example, if a gateway listener is configured to port `80` and the `mapPrivilegedContainerPorts` field is configured to `2000`, then the actual port number on the underlying container is `2080`.
|
|
|
|
You can set the `mapPrivilegedContainerPorts` parameter in the following map in your Consul values file:
|
|
|
|
```yaml
|
|
connectInject:
|
|
apiGateway:
|
|
managedGatewayClass:
|
|
mapPrivilegedContainerPorts: <value>
|
|
```
|
|
|
|
## Supported versions of the Kubernetes gateway API specification
|
|
|
|
Refer to the [release notes](/consul/docs/release-notes) for your version of Consul.
|
|
|
|
## Supported Kubernetes gateway specification features
|
|
|
|
Consul API gateways for Kubernetes support a subset of the Kubernetes Gateway API specification. For a complete list of features, including the list of gateway and route statuses and an explanation on how they
|
|
are used, refer to the [documentation in our GitHub repo](https://github.com/hashicorp/consul-api-gateway/blob/main/dev/docs/supported-features.md):
|
|
|
|
### `GatewayClass`
|
|
|
|
The `GatewayClass` resource describes a class of gateway configurations to use a template for creating `Gateway` resources. You can also specify custom API gateway configurations in a `GatewayClassConfig` CRD and attach them to resource to the `GatewayClass` using the `parametersRef` field.
|
|
|
|
You must specify the `"hashicorp.com/consul-api-gateway-controller"` controller so that Consul can manage gateways generated by the `GatewayClass`. Refer to the [Kubernetes `GatewayClass` documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.GatewayClass) for additional information.
|
|
|
|
### `Gateway`
|
|
|
|
The `Gateway` resource is the core API gateway component. Gateways have one or more listeners that can route `HTTP`, `HTTPS`, or `TCP` traffic. You can define header-based hostname matching for listeners, but SNI is not supported.
|
|
|
|
You can apply filters to add, remove, and set header values on incoming requests. Gateways support the `terminate` TLS mode and `core/v1/Secret` TLS certificates. Extended option support includes TLS version and cipher constraints. Refer to [Kubernetes `Gateway` resource configuration reference](/consul/docs/connect/gateways/api-gateway/configuration/gateway) for more information.
|
|
|
|
### `HTTPRoute`
|
|
|
|
`HTTPRoute` configurations determine HTTP paths between listeners defined on the gateway and services in the mesh. You can specify weights to load balance traffic, as well as define rules for matching request paths, headers, queries, and methods to ensure that traffic is routed appropriately. You can apply filters to add, remove, and set header values on requests sent through th route.
|
|
|
|
Routes support the following backend types:
|
|
|
|
- `core/v1/Service` backend types when the route maps to service registered with Consul.
|
|
- `api-gateway.consul.hashicorp.com/v1alpha1/MeshService`.
|
|
|
|
Refer to [Kubernetes `HTTPRoute` documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.HTTPRoute) for additional information.
|
|
|
|
### `TCPRoute`
|
|
|
|
`TCPRoute` configurations determine TCP paths between listeners defined on the gateway and services in the mesh. Routes support the following backend types:
|
|
|
|
- `core/v1/Service` backend types when the route maps to service registered with Consul.
|
|
- `api-gateway.consul.hashicorp.com/v1alpha1/MeshService`.
|
|
|
|
Refer to [Kubernetes `TCPRoute` documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.TCPRoute) for additional information.
|
|
|
|
### `ReferenceGrant`
|
|
|
|
`ReferenceGrant` resources allow resources to reference resources in other namespaces. They are required to allow references from a `Gateway` to a Kubernetes `core/v1/Secret` in a different namespace. Without a `ReferenceGrant`, `backendRefs` attached to the gateway may not be permitted. As a result, the `ReferenceGrant` sets a `ResolvedRefs` status to `False` with the reason `InvalidCertificateRef`, which prevents the gateway from becoming ready.
|
|
|
|
`ReferenceGrant` resources are also required for references from an `HTTPRoute` or `TCPRoute` to a Kubernetes `core/v1/Service` in a different namespace. Without a `ReferenceGrant`, `backendRefs` attached to the route may not be permitted. As a result, Kubernetes sets a `ResolvedRefs` status to `False` with the reason `RefNotPermitted`, which causes the gateway listener to reject the route.
|
|
|
|
If a route `backendRefs` becomes unpermitted, the entire route is removed from the gateway listener. A `backendRefs` can become unpermitted when you delete a `ReferenceGrant` or add a new unpermitted `backendRefs` to an existing route.
|
|
|
|
Refer to the [Kubernetes `ReferenceGrant` documentation](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.ReferenceGrant) for additional information.
|
|
|
|
## Consul server deployments
|
|
|
|
- Consul Enterprise and the community edition are both supported.
|
|
- Supported Consul Server deployment types:
|
|
- Self-Managed
|
|
- HCP Consul Dedicated
|
|
|
|
### Consul feature support
|
|
|
|
API gateways on Kubernetes support all Consul features, but you can only route traffic between multiple datacenters through peered connections. Refer to [Route Traffic to Peered Services](/consul/docs/connect/gateways/api-gateway/define-routes/route-to-peered-services) for additional information. WAN federation is not supported.
|
|
|
|
## Deployment Environments
|
|
|
|
Consul API gateway can be deployed in the following Kubernetes-based environments:
|
|
|
|
- Standard Kubernetes environments
|
|
- AWS Elastic Kubernetes Service (EKS)
|
|
- Google Kubernetes Engine (GKE)
|
|
- Azure Kubernetes Service (AKS)
|
|
|
|
## Resource allocations
|
|
|
|
The following resources are allocated for each component of the API gateway.
|
|
|
|
### Gateway controller pod
|
|
|
|
- **CPU**: None. Either the namespace or cluster default is allocated, depending on the Kubernetes cluster configuration.
|
|
- **Memory**: None. Either the namespace or cluster default is allocated, depending on the Kubernetes cluster configuration.
|
|
|
|
### Gateway instance pod
|
|
|
|
- **CPU**: None. Either the namespace or cluster default is allocated, depending on the Kubernetes cluster configuration.
|
|
- **Memory**: None. Either the namespace or cluster default is allocated, depending on the Kubernetes cluster configuration.
|