consul/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx

218 lines
8.9 KiB
Plaintext
Raw Normal View History

2022-07-05 22:53:56 +00:00
---
layout: docs
page_title: GatewayClassConfig Resource Configuration
description: >-
The `GatewayClassConfig` resource specifies connection information and settings that Consul API Gateway uses to connect to Consul. Learn about its configuration model and reference specifications, and review an example configuration.
2022-07-05 22:53:56 +00:00
---
# GatewayClassConfig Resource Configuration
2022-07-05 22:53:56 +00:00
This topic provides full details about the `GatewayClassConfig` resource.
## Introduction
2022-07-26 14:31:27 +00:00
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.
2022-07-26 17:34:10 +00:00
* [`consul`](#consul): object | optional
* [`address`](#consul-address): string | optional
* [`authentication`](#consul-authentication): object | optional
* [`account`](#consul-authentication-account): string | optional
2022-07-26 17:34:10 +00:00
* [`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
* [`matchPrivilegedContainerPorts`](#matchPrivilegedContainerPorts): integer | optional
2022-07-26 17:34:10 +00:00
* [`nodeSelector`](#nodeselector): string | optional
* [`openshiftSCCName`](#openshiftSCCName): string | optional
2022-07-26 17:34:10 +00:00
* [`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](/consul/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`
### matchPrivilegedContainerPorts
Specifies a value that Consul adds to privileged ports defined in the gateway. Privileged ports are port numbers less than 1024 and some platforms, such as Red Hat OpenShift, explicitly configure Kubernetes to avoid running containers on privileged ports. The total value of the configured port number and the `matchPriviledgedContainerPorts` value must not exceed 65535, which is the highest possible TCP port number allowed.
for gateway containers
* Type: Integer
* Required: optional
You can specify an integer between `0` and `64512`
### 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
### openshiftSCCName
Specifies the OpenShift security context constraint (SCC) for the `GatewayClassConfig` to use. Refer to the [OpenShift SCC documentation](https://docs.openshift.com/container-platform/4.13/authentication/managing-security-context-constraints.html#default-sccs_configuring-internal-oauth) for additional information about the available default SCCs.
* Type: string
* Required: optional
* Default: `restricted-v2`
### 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
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 <nathan.coleman@hashicorp.com> Co-authored-by: Sarah Alsmiller <sarah.alsmiller@hashicorp.com> Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> Co-authored-by: sarahalsmiller <100602640+sarahalsmiller@users.noreply.github.com>
2022-11-17 23:42:25 +00:00
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`:
2022-07-05 22:53:56 +00:00
<CodeBlockConfig filename="gateway.yaml">
```yaml
apiVersion: api-gateway.consul.hashicorp.com/v1alpha1
kind: GatewayClassConfig
metadata:
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 <nathan.coleman@hashicorp.com> Co-authored-by: Sarah Alsmiller <sarah.alsmiller@hashicorp.com> Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> Co-authored-by: sarahalsmiller <100602640+sarahalsmiller@users.noreply.github.com>
2022-11-17 23:42:25 +00:00
name: example-gateway-class-config
2022-07-05 22:53:56 +00:00
spec:
useHostPorts: true
logLevel: 'trace'
consul:
scheme: 'https'
ports:
http: 8501
grpc: 8502
2022-07-14 17:54:40 +00:00
```
2022-07-05 22:53:56 +00:00
</CodeBlockConfig>
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.