From 8fe5c14d80b2e7326e79cad25d96ab6387c354f6 Mon Sep 17 00:00:00 2001 From: Sarah Alsmiller Date: Mon, 25 Jul 2022 21:57:30 -0500 Subject: [PATCH] updated all pages to follow cm/s specification --- .../api-gateway/configuration/gateway.mdx | 44 ++--- .../configuration/gatewayclass.mdx | 51 ++++- .../configuration/gatewayclassconfig.mdx | 177 +++++++++++++++--- 3 files changed, 227 insertions(+), 45 deletions(-) diff --git a/website/content/docs/api-gateway/configuration/gateway.mdx b/website/content/docs/api-gateway/configuration/gateway.mdx index fda00c9066..b340d3c329 100644 --- a/website/content/docs/api-gateway/configuration/gateway.mdx +++ b/website/content/docs/api-gateway/configuration/gateway.mdx @@ -29,27 +29,27 @@ Specify the following parameters to declare a Gateway: ## Configuration model -* `gatewayClassName`: string | required -* `listeners`: array of objects | required - * `allowedRoutes`: object | required - * `namespaces`: object | required - * `from`: string | required - * `selector`: object | required if from is configured to selector - * `matchExpressions`: array of objects | required if matchLabels is not configured - * `key`: string | required if matchExpressions is declared - * `operator`: string | required if matchExpressions is declared - * `values`: array of strings | required if matchExpressions is declared - * `matchLabels`: map of strings | required if matchExpressions is not configured - * `hostname`: string | required - * `name`: string | required - * `port`: integer | required - * `protocol`: string | required - * `tls`: object | required if protocol is set to HTTPS - * `certificateRefs`: array or objects | required if tls is declared - * `name`: string | required if certificateRefs is declared - * `namespace`: string | required if certificateRefs is declared - * `mode`: string | required if certificateRefs is declared - * `options`: map of strings | optional +* (`gatewayClassName`)[###gatewayClassName]: string | required +* (`listeners`)[###listeners]: array of objects | required + * (`allowedRoutes`)[###listeners.allowedRoutes]: object | required + * (`namespaces`}[###listeners.namespaces]: object | required + * (`from`)[###listeners.namespaces.from]: string | required + * (`selector`)[###listeners.namespaces.selector]: object | required if from is configured to selector + * (`matchExpressions`)[###listeners.namespaces.selector.matchExpressions]: array of objects | required if matchLabels is not configured + * (`key`)[###listeners.namespaces.selector.matchExpressions.key]: string | required if matchExpressions is declared + * (`operator`)[###listeners.namespaces.selector.operator]: string | required if matchExpressions is declared + * (`values`)[###listeners.namespaces.selector.values]: array of strings | required if matchExpressions is declared + * (`matchLabels`)[###listeners.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.certificateRefs]: array or objects | required if tls is declared + * (`name`)[###listeners.tls.certificateRefs.name]: string | required if certificateRefs is declared + * (`namespace`)[###listeners.tls.certificateRefs.namespace]: string | required if certificateRefs is declared + * (`mode`)[###listeners.tls.mode]: string | required if certificateRefs is declared + * (`options`)[###listeners.tls.options]: map of strings | optional ## Specification @@ -99,7 +99,7 @@ The selector configuration contains one of the following objects: 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 | -|:-----------:|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|:----------------:| +|:----------- |:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |:---------------- | |`key` | Specifies that label that the key applies to. | string | |`operator` | Specifies the key's relation to a set of values. The following values are valid:In: description of what this means NotIn: description of what this means Exists: description of what this means DoesNotExist: description of what this means | string | |`values` | Specifies an array of string values. If the operator is configured to In or NotIn,the values array must be non-empty. If theoperator is Exists or DoesNotExist, the values array must be empty. This array is replaced during a strategic merge patch. | array of strings | diff --git a/website/content/docs/api-gateway/configuration/gatewayclass.mdx b/website/content/docs/api-gateway/configuration/gatewayclass.mdx index 33fa17b193..2a5104f518 100644 --- a/website/content/docs/api-gateway/configuration/gatewayclass.mdx +++ b/website/content/docs/api-gateway/configuration/gatewayclass.mdx @@ -7,13 +7,62 @@ description: >- # GatewayClass +This topic provides full details about the `GatewayClass` resource + +## Introduction + 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 `GatewayClass` resource is a generic kubernetes gateway object. For configuration specific to Consul API Gateway, see [GatewayClassConfig](/docs/api-gateway/configuration/gatewayclassconfig). + +## Configuration model + +* (`controllerName`)[###controllerName]: string | required +* (`parametersRef`)[###parametersRef]: object | optional + * (`group`)[###parametersRef.group]: Group | required is parametersRef is set + * (`kind`)[###parametersRef.kind]: Kind | required is parametersRef is set + * (`name`)[###parametersRef.name]: string | required is parametersRef is set +* (`description`)[###description]: string | optional + +## Specification + +This topic provides details about the configuration parameters. + +### controllerName +The name of the controller that is managing the gateways of this class. When using Consul API Gateway, this value should be equal to `'hashicorp.com/consul-api-gateway-controller'` +* Type: string +* Required: required + +### parametersRef +An object that defines additional configuration required by the gateway controller. +* Type: object +* Required: required + +### parametersRef.group +When using Consul API Gateway, this value should be equal to `api-gateway.consul.hashicorp.com` +* Type: Group +* Required: required + +### parametersRef.kind +When using Consul API Gateway, this value should be equal to `GatewayClassConfig` +* Type: object +* Required: required + +### parametersRef.name +The name of the `GatewayClass` +* Type: object +* Required: required + +### description +Helps describe a gateway class with more details +* Type: string +* Required: optional + +## Complete Configuration The following example creates a gateway class called `test-gateway-class`: diff --git a/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx b/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx index 3cdebb1884..5b35c04aa7 100644 --- a/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx +++ b/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx @@ -7,9 +7,156 @@ description: >- # GatewayClassConfig +This topic provides full details about the `GatewayClassConfig` resource + +## Introduction + 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. +A `GatewayClassConfig` object provides configuration options specifc to Consul API Gateway + +## Configuration model + +* (`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 +* 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 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 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 namespace to use for authentication. +* Type: integer +* Required: optional +* Default: `8500` + +### consul.scheme +Specifies the scheme to use for connecting to Consul. The supported values are `"http"` and `"https"`. +* Type: string +* Required: optional +* Default: `http` + +### copyAnnotations.service +List 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 +The image to use for consul-api-gateway. View available image tags on [DockerHub](https://hub.docker.com/r/hashicorp/consul-api-gateway/tags). + +Most deployments will use the default value unless a specific version of the Consul API Gateway is desired. +* Type: string +* Required: optional +* Default: `"hashicorp/consul-api-gateway:RELEASE_VERSION"` + +### image.envoy +The image to use for consul-api-gateway. View available image tags on [DockerHub](https://hub.docker.com/r/hashicorp/consul-api-gateway/tags). + +Most deployments will use the default value unless a specific version of Envoy is desired. +* Type: string +* Required: optional +* Default: `"envoyproxy/envoy:RELEASE_VERSION"` + +### logLevel +Specifies the error reporting level for logs. You can specify the following values: `error`, `warning`, `info`, `debug`, `trace`. +* Type: string +* Required: optional +* Default: `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.* Type: string +* Required: optional + +### serviceType +Specifies the ingress methods for a service. The following values are supported:
`ClusterIP`
`NodePort`
`LoadBalancer`. +* Type: string +* Required: optional + +### useHostPorts +If set to `true`, then the Envoy container ports are mapped to host ports. +* Type: boolean +* Required: optional +* Default: `false` + + +## Full Configuration The following example creates a gateway class configuration called `test-gateway-class-config`: @@ -30,27 +177,13 @@ The following example creates a gateway class configuration called `test-gateway ``` -The following table describes the allowed parameters for the `spec` array: -| Parameter | Description | Type | Default | -| --- | --- | ---- | ------- | -| `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. | String | A local agent on the host where the pod is running. | -| `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` | + + + | String | `"hashicorp/consul-api-gateway:RELEASE_VERSION"` | + | String | `"info"` | +| `nodeSelector` | | Object | N/A | +| `serviceType` | | String | N/A | +| `useHostPorts` | | 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.