updated all pages to follow cm/s specification

This commit is contained in:
Sarah Alsmiller 2022-07-25 21:57:30 -05:00
parent 02d441f625
commit 9d165e8ce8
3 changed files with 227 additions and 45 deletions

View File

@ -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 |

View File

@ -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`:
<CodeBlockConfig filename="gateway.yaml">

View File

@ -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: <br/>`ClusterIP` <br/>`NodePort` <br/>`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`:
<CodeBlockConfig filename="gateway.yaml">
@ -30,27 +177,13 @@ The following example creates a gateway class configuration called `test-gateway
```
</CodeBlockConfig>
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: <br/>`ClusterIP` <br/>`NodePort` <br/>`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.