From 952ebb7b9383afe54bea60e9860daba6d39f0b1b Mon Sep 17 00:00:00 2001 From: Sarah Alsmiller Date: Tue, 5 Jul 2022 17:53:56 -0500 Subject: [PATCH 001/124] restructure documentation --- .../api-gateway/configuration/gateway.mdx | 316 +++++++++++++ .../configuration/gatewayclass.mdx | 37 ++ .../configuration/gatewayclassconfig.mdx | 57 +++ .../docs/api-gateway/configuration/index.mdx | 17 + .../docs/api-gateway/configuration/routes.mdx | 89 ++++ .../consul-api-gateway-install.mdx | 429 +++--------------- website/content/docs/api-gateway/index.mdx | 2 +- .../content/docs/api-gateway/tech-specs.mdx | 70 --- ...ade-specific-versions.mdx => upgrades.mdx} | 0 .../docs/api-gateway/usage/basic-usage.mdx | 131 ++++++ website/data/docs-nav-data.json | 44 +- 11 files changed, 741 insertions(+), 451 deletions(-) create mode 100644 website/content/docs/api-gateway/configuration/gateway.mdx create mode 100644 website/content/docs/api-gateway/configuration/gatewayclass.mdx create mode 100644 website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx create mode 100644 website/content/docs/api-gateway/configuration/index.mdx create mode 100644 website/content/docs/api-gateway/configuration/routes.mdx delete mode 100644 website/content/docs/api-gateway/tech-specs.mdx rename website/content/docs/api-gateway/{upgrade-specific-versions.mdx => upgrades.mdx} (100%) create mode 100644 website/content/docs/api-gateway/usage/basic-usage.mdx diff --git a/website/content/docs/api-gateway/configuration/gateway.mdx b/website/content/docs/api-gateway/configuration/gateway.mdx new file mode 100644 index 0000000000..c1dd183268 --- /dev/null +++ b/website/content/docs/api-gateway/configuration/gateway.mdx @@ -0,0 +1,316 @@ +--- +layout: docs +page_title: Consul API Gateway Gateway +description: >- +Consul API Gateway Gateway +--- + +# Gateway + +This topic provides full details about the `Gateway` resource. + +## Introduction + +A `Gateway` is an instance of network infrastructure that determines how service traffic should be handled. A `Gateway` contains one or more `listeners` that bind to a set of IP addresses. An `HTTPRoute` or `TCPRoute` can then attach to a gateway listener to direct traffic from the gateway to a service. + +Gateway instances derive their configurations from the `GatewayClass` resource, which acts as a template for individual `Gateway` deployments. Refer to [GatewayClass](/docs/api-gateway/configuration/gatewayclass) for additional information. + +Specify the following parameters to declare a Gateway: + +| Parameter | Description | Required | +|:-----------:|:----------------------------------------------------------------------------------------------------------------------------------------------------------:|:--------:| +| kind | Specifies the type of configuration object. The value should always be Gateway | Required | +| description | Human-readable string for describing the purpose of the Gateway. | Optional | +| version | Specifies the Kubernetes API version. The value should always be gateway.networking.k8s.io/v1alpha2 | Required | +| scope | Specifies the effective scope of the Gateway. The value should always be namespaced. | Required | +| fields | Specifies the configurations for the Gateway. The fields are listed in the Configuration model. Details for each field are described in the Specification. | Required | + + + +## 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 + +## Specification + +This topic provides details about the configuration parameters + +### gatewayClassName +Specifies the name of the `GatewayClass` resource used for the `Gateway` instance. +* Type: string +* Required: required + +### listeners +Specifies the `listeners` associated with the `Gateway`. At least one `listener` must be specified. Each `listener` within a `Gateway` must have a unique combination of `hostname`, `port`, and `protocol`. + +* Type: array of objects +* Required: required + +### listeners.allowedRoutes +Specifies a `namespace` object that defines the types of routes that may be attached to a listener. +* Type: object +* Required: required + +### listeners.allowedRoutes.namespaces +Determines which routes are allowed to attach to the `listener`. Only routes in the same namespace as the `Gateway` may be attached by default. + +### listeners.allowedRoutes.namespaces.from +Specifies the policy for which namespaces a route may attach to a `Gateway` from. Defaults to `Same`. + +This parameter has the following properties: +* Type: string +* Required: required + +You can specify one of the following strings: +* All: Routes in all namespaces may be attached to the Gateway. +* Same: Only routes in the same namespace as the Gateway may be attached. +* Selector: Only routes in namespaces that match the selector configuration may be attached. + +### listeners.allowedRoutes.namespaces.selector +The `selector` configuration matches zero or more namespaces that determine which routes are allowed to attach to the listener. +* Type: Object +* Required: Required when from is configured to selector. + +The selector configuration contains one of the following objects: +* matchExpressions +* matchLabels + +### listeners.allowedRoutes.namespaces.selector.matchExpressions +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 | +| scope | Specifies the effective scope of the Gateway. The value should always be namespaced. | Required | +| fields | Specifies the configurations for the Gateway. The fields are listed in the Configuration model. Details for each field are described in the Specification. | Required | + +```yaml +namespaceSelector: + matchExpressions: + - key: kubernetes.io/metadata.name + operator: In + values: + - foo + - bar +``` + +### listeners.allowedRoutes.namespaces.selector.matchLabels +Specifies an array of labels and label values. If a match is found, then routes with the matching label(s) are allowed to attach to the `Gateway`. This selector can contain any arbitrary key/value pair. + +```yaml +namespaceSelector: + matchLabels: + foo: bar +``` + +For more on labels, see [Labels and Selectors](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) + +### listeners.hostname +Specifies the `listeners` hostname +* Type: string +* Required: required + +### listeners.name +Specifies the `listeners` name +* Type: string +* Required: required + +### listeners.port +Specifies the port number that the `listener` will attach to +* Type: integer +* Required: required + +### listeners.protocol +Specifies the protocol the `listener` will use +* Type: string +* Required: required + +Allowed values `TCP`, `HTTP`, `HTTPS` + +### listeners.tls +* Type: Object +* Required: required if protocol is set to HTTPS + +### listeners.tls.certificateRefs +`CertificateRefs` contains a series of references to Kubernetes objects that contains TLS certificates and private keys. These certificates are used to establish a TLS handshake for requests that match the hostname of the associated `listener`. Each reference must be a Kubernetes Secret, and, if using a Secret in a namespace other than the`Gateway`'s, must have a corresponding `ReferencePolicy` created. +* Type: Object or Array +* Required: required if tls is set + +### listeners.tls.mode +* Type: String +* Required: required if certificateRefs is set + +### listeners.tls.options +* Type: Map of Strings +* Required: optional + +## Complete configuration +The following example shows a fully configured Gateway. + +```yaml +kind: Gateway +Description: This gateway enables traffic from A to B. +version: gateway.networking.k8s.io/v1alpha2 +scope: Namespaced +fields: + - name: addresses + supported: false + - name: gatewayClassName + type: string + description: Name of a GatewayClass resource used for this Gateway. + - name: listeners + type: array + description: | + Description of the listeners associated with this Gateway. + items: + fields: + - name: allowedRoutes + type: object + description: | + AllowedRoutes defines the types of routes that + MAY be attached to a Listener and the trusted namespaces where + those Route resources MAY be present. + fields: + - name: kinds + supported: false + - name: namespaces + type: object + description: | + Description of namespaces from which routes may be attached to this Listener. This is restricted + to the namespace of this Gateway by default. + fields: + - name: from + type: string + default: Same + description: | + From indicates where Routes will be selected + for this Gateway." + enum: ["All", "Selector", "Same"] + - name: selector + type: object + description: "Selector must be specified when From is + set to \"Selector\". In that case, only Routes in + Namespaces matching this Selector will be selected + by this Gateway." + fields: + - name: matchExpressions + type: array + description: | + matchExpressions is a list of label + selector requirements. The requirements are ANDed. + items: + fields: + - name: key + type: string + description: | + key is the label key that the + selector applies to. + - name: operator + type: string + description: | + operator represents a key's relationship + to a set of values. Valid operators are + In, NotIn, Exists and DoesNotExist. + - name: values + type: array + description: | + values is an array of string + values. If the operator is In or NotIn, + the values array must be non-empty. If the + operator is Exists or DoesNotExist, the + values array must be empty. This array is + replaced during a strategic merge patch. + - name: matchLabels + type: map + description: | + matchLabels is a map of {key,value} + pairs. A single {key,value} in the matchLabels + map is equivalent to an element of matchExpressions, + whose key field is "key", the operator is "In", + and the values array contains only "value". The + requirements are ANDed. + - name: hostname + type: string + description: | + Hostname specifies the virtual hostname to match for HTTP or HTTPS-based listeners. When unspecified, + all hostnames are matched. This is implemented by checking the HTTP Host header sent on a client request. + - name: name + type: string + description: "Name is the name of the Listener. This name MUST be unique within a Gateway." + - name: port + type: integer + description: "Port is the network port of a listener." + - name: protocol + type: string + description: "Protocol specifies the network protocol this listener expects to receive." + enum: ["HTTP", "HTTPS", "TCP"] + - name: tls + type: object + description: | + TLS is the TLS configuration for the Listener. + This field is required if the Protocol field is "HTTPS". + It is invalid to set this field if the Protocol + field is "HTTP" or "TCP". + fields: + - name: certificateRefs + type: array + description: | + CertificateRefs contains a series of references + to Kubernetes objects that contains TLS certificates and + private keys. These certificates are used to establish + a TLS handshake for requests that match the hostname of + the associated listener. Each reference must be a Kubernetes + Secret, and, if using a Secret in a namespace other than the + Gateway's, must have a corresponding ReferencePolicy created. + items: + fields: + - name: group + supported: false + - name: kind + supported: false + - name: name + type: string + description: Name is the name of the Kubernetes Secret. + - name: namespace + type: string + description: | + Namespace is the namespace of the Secret. When unspecified, the local namespace is inferred. + + Note that when a namespace is specified, a ReferencePolicy + object is required in the specified namespace to + allow that namespace's owner to accept the reference. + - name: mode + type: string + default: Terminate + description: "Mode defines the TLS behavior for the TLS session initiated by the client. The only supported mode at this time is `Terminate`" + enum: ["Terminate"] + - name: options + type: map + description: | + Options are a list of key/value pairs to enable + extended TLS configuration for each implementation. + enum: ["api-gateway.consul.hashicorp.com/tls_min_version","api-gateway.consul.hashicorp.com/tls_max_version","api-gateway.consul.hashicorp.com/tls_cipher_suites",] +``` + diff --git a/website/content/docs/api-gateway/configuration/gatewayclass.mdx b/website/content/docs/api-gateway/configuration/gatewayclass.mdx new file mode 100644 index 0000000000..2a80fb683d --- /dev/null +++ b/website/content/docs/api-gateway/configuration/gatewayclass.mdx @@ -0,0 +1,37 @@ +--- +layout: docs +page_title: Consul API Gateway GatewayClass +description: >- +Consul API Gateway GatewayClass +--- + +# 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. + diff --git a/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx b/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx new file mode 100644 index 0000000000..7648b04736 --- /dev/null +++ b/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx @@ -0,0 +1,57 @@ +--- +layout: docs +page_title: Consul API Gateway GatewayClassConfig +description: >- +Consul API Gateway GatewayClassConfig +--- + +# 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 configuration 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"]` | +| `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` | + +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. diff --git a/website/content/docs/api-gateway/configuration/index.mdx b/website/content/docs/api-gateway/configuration/index.mdx new file mode 100644 index 0000000000..ebdaaeb6fa --- /dev/null +++ b/website/content/docs/api-gateway/configuration/index.mdx @@ -0,0 +1,17 @@ +--- +layout: docs +page_title: Consul API Gateway Configuration +description: >- +Consul API Gateway Configuration +--- + +# Configuration + +This topic provides an overview of the configuration items that enable Consul API Gateway to facilitate ingress into your Consul service mesh. + +- [Gateway](/docs/api-gateway/configuration/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](/docs/api-gateway/configuration/gateway#listeners)), which specify the logical endpoints bound to the gateway's addresses. Refer to Configuration > Gateway for details on configuration. +- [GatewayClassConfig](/docs/api-gateway/configuration/gatewayclassconfig): Describes additional Consul API Gateway-related configuration parameters for the GatewayClass resource. +- [GatewayClass](/docs/api-gateway/configuration/gatewayclass): Defines a class of gateway resources that you can use as a template for creating gateways. +- [Routes](/docs/api-gateway/configuration/routes): Specifies the path from the gateway to the backend service(s)client to the listener. + + diff --git a/website/content/docs/api-gateway/configuration/routes.mdx b/website/content/docs/api-gateway/configuration/routes.mdx new file mode 100644 index 0000000000..987e8193ab --- /dev/null +++ b/website/content/docs/api-gateway/configuration/routes.mdx @@ -0,0 +1,89 @@ +--- +layout: docs +page_title: Consul API Gateway Routes +description: >- +Consul API Gateway Routes +--- + +# 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 + ``` + + + +To create a route for a `backendRef` in a different namespace, you must also +create a [ReferencePolicy](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.ReferencePolicy). + +The following example creates a route named `example-route` in namespace `gateway-namespace`. This route has a `backendRef` in namespace `service-namespace`. Traffic is allowed because the `ReferencePolicy`, named `reference-policy` in namespace `service-namespace`, allows traffic from `HTTPRoutes` in `gateway-namespace` to `Services` in `service-namespace`. + + + + ```yaml + apiVersion: gateway.networking.k8s.io/v1alpha2 + kind: HTTPRoute + metadata: + name: example-route + namespace: gateway-namespace + spec: + parentRefs: + - name: example-gateway + rules: + - backendRefs: + - kind: Service + name: echo + namespace: service-namespace + port: 8080 + --- + + apiVersion: gateway.networking.k8s.io/v1alpha2 + kind: ReferencePolicy + metadata: + name: reference-policy + namespace: service-namespace + spec: + from: + - group: gateway.networking.k8s.io + kind: HTTPRoute + namespace: gateway-namespace + to: + - group: "" + kind: Service + name: echo + ``` + + + +## MeshService + +The `MeshService` configuration 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. diff --git a/website/content/docs/api-gateway/consul-api-gateway-install.mdx b/website/content/docs/api-gateway/consul-api-gateway-install.mdx index fb48565baa..6c62f6719e 100644 --- a/website/content/docs/api-gateway/consul-api-gateway-install.mdx +++ b/website/content/docs/api-gateway/consul-api-gateway-install.mdx @@ -11,7 +11,64 @@ This topic describes how to use the Consul API Gateway add-on module. It include ## Requirements -Ensure that the environment you are deploying Consul API Gateway in meets the requirements listed in the [Technical Specifications][tech-specs]. This includes validating that the requirements for minimum versions of software are met. See the [Release Notes][rel-notes] for the version of API Gateway you are deploying. +Verify that your environment meets the following requirements prior to using Consul API Gateway. + +### Datacenter Requirements + +Your datacenter must meet the following requirements prior to configuring the Consul API Gateway: + +- Kubernetes 1.21+ +- Kubernetes 1.24 is not supported at this time. +- `kubectl` 1.21+ +- Consul 1.11.2+ +- HashiCorp Consul Helm chart 0.45.0+ +- Consul Service Mesh must be deployed on the Kubernetes cluster that API Gateway is deployed on. +- Envoy: Envoy proxy support is determined by the Consul version deployed. Refer to [Envoy Integration](/docs/connect/proxies/envoy) for details. + +### TCP Port Requirements + +The following table describes the TCP port requirements for each component of the API Gateway. + +| Port | Description | Component | +| ---- | ----------- | --------- | +| 9090 | Secret discovery service (SDS) | Gateway controller pod
Gateway instance pod | +| 20000 | Kubernetes readiness probe | Gateway instance pod | +| Configurable | Port for scraping Prometheus metrics. Disabled by default. | Gateway controller pod | + +## Consul Server Deployments + +- Consul Editions supported: OSS and Enterprise +- Supported Consul Server deployment types: +- Self-Managed +- HCP Consul + +## Deployment Environments + +Consul API Gateway can be deployed in the following Kubernetes-based environments: + +- Generic Kubernetes +- AWS Elastic Kubernetes Service (EKS) +- Google Kubernetes Engine (GKE) +- Azure Kubernetes Service (AKS) + +## Kubernetes Gateway API Specification - Supported Versions + +See the Release Notes for the version of Consul API Gateway being used. + +## 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 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. + ## Installation @@ -47,379 +104,9 @@ Ensure that the environment you are deploying Consul API Gateway in meets the re $ helm install consul hashicorp/consul --version 0.45.0 --values values.yaml --create-namespace --namespace consul ``` -## 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). - - - - ```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. - --> **Note:** Add the following `managedGatewayClass` configuration to the `values.yaml` Helm configuration to enable the `GatewayClassConfig` and `GatewayClass` to be created automatically. The gateway, listeners, and routes will need to be configured manually. When `managedGatewayClass` is enabled, the [`serviceType`](/docs/k8s/helm#v-apigateway-managedgatewayclass-servicetype) for a managed `GatewayClass` will also default to `LoadBalancer`, which is appropriate for most deployments to managed Kubernetes cloud offerings (i.e., EKS, GKE, AKS). Other deployments, such as to a [kind](https://kind.sigs.k8s.io/) cluster, may require specifying `NodePort` or `ClusterIP`, instead. - -### 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 configuration 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"]` | -| `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` | - -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 -``` - - - -For a listener's `certificateRef` to reference a secret in a different namespace, you must also create a [ReferencePolicy](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.ReferencePolicy). - -The following example creates a `Gateway` named `example-gateway` in `gateway-namespace`. This `Gateway` has a `certificateRef` in `secret-namespace`. -The reference is allowed because `reference-policy` in `secret-namespace` lets `Gateways` in `gateway-namespace` reference `Secrets` in `secret-namespace`. - - - -```yaml -apiVersion: gateway.networking.k8s.io/v1alpha2 -kind: Gateway -metadata: - name: example-gateway - namespace: gateway-namespace - 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 - namespace: secret-namespace ---- - -apiVersion: gateway.networking.k8s.io/v1alpha2 -kind: ReferencePolicy -metadata: - name: reference-policy - namespace: secret-namespace -spec: - from: - - group: gateway.networking.k8s.io - kind: Gateway - namespace: gateway-namespace - to: - - group: "" - kind: Secret - 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 further 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. - -#### Scaling - -You can scale a logical gateway object to multiple instances with the [`kubectl scale`](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#scaling-a-deployment) command. The object scales according to the bounds set in `GatewayClassConfig`. - -```shell-session -$ kubectl get deployment --selector api-gateway.consul.hashicorp.com/name=example-gateway -NAME READY UP-TO-DATE AVAILABLE -example-gateway 1/1 1 1 -``` -```shell-session -$ kubectl scale deployment/example-gateway --replicas=3 -deployment.apps/example-gateway scaled -``` -```shell-session -$ kubectl get deployment --selector api-gateway.consul.hashicorp.com/name=example-gateway -NAME READY UP-TO-DATE AVAILABLE -example-gateway 3/3 3 3 -``` - -### 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 -``` - - - -To create a route for a `backendRef` in a different namespace, you must also -create a [ReferencePolicy](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.ReferencePolicy). - -The following example creates a route named `example-route` in namespace `gateway-namespace`. This route has a `backendRef` in namespace `service-namespace`. Traffic is allowed because the `ReferencePolicy`, named `reference-policy` in namespace `service-namespace`, allows traffic from `HTTPRoutes` in `gateway-namespace` to `Services` in `service-namespace`. - - - -```yaml -apiVersion: gateway.networking.k8s.io/v1alpha2 -kind: HTTPRoute -metadata: - name: example-route - namespace: gateway-namespace -spec: - parentRefs: - - name: example-gateway - rules: - - backendRefs: - - kind: Service - name: echo - namespace: service-namespace - port: 8080 ---- - -apiVersion: gateway.networking.k8s.io/v1alpha2 -kind: ReferencePolicy -metadata: - name: reference-policy - namespace: service-namespace -spec: - from: - - group: gateway.networking.k8s.io - kind: HTTPRoute - namespace: gateway-namespace - to: - - group: "" - kind: Service - name: echo -``` - - - -### MeshService - -The `MeshService` configuration 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. -[tech-specs]: /docs/api-gateway/tech-specs [rel-notes]: /docs/release-notes diff --git a/website/content/docs/api-gateway/index.mdx b/website/content/docs/api-gateway/index.mdx index a5bfd9dc8e..8ec1c0f5a6 100644 --- a/website/content/docs/api-gateway/index.mdx +++ b/website/content/docs/api-gateway/index.mdx @@ -18,7 +18,7 @@ Consul API Gateway solves the following primary use cases: - **Controlling access at the point of entry**: Consul API Gateway allows users to set the protocols of external connection requests and provide clients with TLS certificates from trusted providers (e.g., Verisign, Let’s Encrypt). - **Simplifying traffic management**: The Consul API Gateway can load balance requests across services and route traffic to the appropriate service by matching one or more criteria, such as hostname, path, header presence or value, and HTTP Method type (e.g., GET, POST, PATCH). -## Implementation +## How Does Consul API Gateway Work? Consul API Gateway can be deployed on Kubernetes-based runtime environments and requires that Consul service mesh be deployed on the Kubernetes cluster. diff --git a/website/content/docs/api-gateway/tech-specs.mdx b/website/content/docs/api-gateway/tech-specs.mdx deleted file mode 100644 index e499349198..0000000000 --- a/website/content/docs/api-gateway/tech-specs.mdx +++ /dev/null @@ -1,70 +0,0 @@ ---- -layout: docs -page_title: Consul API Gateway Technical Specifications -description: >- - This topic describes technical specifications for Consul API Gateway. ---- - -# Technical Specifications - -This topic describes the technical specifications associated with using Consul API Gateway. - -## Requirements - -Verify that your environment meets the following requirements prior to using Consul API Gateway. - -### Datacenter Requirements - -Your datacenter must meet the following requirements prior to configuring the Consul API Gateway: - -- Kubernetes 1.21+ - - Kubernetes 1.24 is not supported at this time. -- `kubectl` 1.21+ -- Consul 1.11.2+ -- HashiCorp Consul Helm chart 0.45.0+ -- Consul Service Mesh must be deployed on the Kubernetes cluster that API Gateway is deployed on. -- Envoy: Envoy proxy support is determined by the Consul version deployed. Refer to [Envoy Integration](/docs/connect/proxies/envoy) for details. - -### TCP Port Requirements - -The following table describes the TCP port requirements for each component of the API Gateway. - -| Port | Description | Component | -| ---- | ----------- | --------- | -| 9090 | Secret discovery service (SDS) | Gateway controller pod
Gateway instance pod | -| 20000 | Kubernetes readiness probe | Gateway instance pod | -| Configurable | Port for scraping Prometheus metrics. Disabled by default. | Gateway controller pod | - -## Consul Server Deployments - -- Consul Editions supported: OSS and Enterprise -- Supported Consul Server deployment types: - - Self-Managed - - HCP Consul - -## Deployment Environments - -Consul API Gateway can be deployed in the following Kubernetes-based environments: - -- Generic Kubernetes -- AWS Elastic Kubernetes Service (EKS) -- Google Kubernetes Engine (GKE) -- Azure Kubernetes Service (AKS) - -## Kubernetes Gateway API Specification - Supported Versions - -See the Release Notes for the version of Consul API Gateway being used. - -## 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 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. diff --git a/website/content/docs/api-gateway/upgrade-specific-versions.mdx b/website/content/docs/api-gateway/upgrades.mdx similarity index 100% rename from website/content/docs/api-gateway/upgrade-specific-versions.mdx rename to website/content/docs/api-gateway/upgrades.mdx diff --git a/website/content/docs/api-gateway/usage/basic-usage.mdx b/website/content/docs/api-gateway/usage/basic-usage.mdx new file mode 100644 index 0000000000..1eae64c4e5 --- /dev/null +++ b/website/content/docs/api-gateway/usage/basic-usage.mdx @@ -0,0 +1,131 @@ +--- +layout: docs +page_title: Consul API Gateway Basic Usage +description: >- +Consul API Gateway Basic Usage +--- + + +# Basic Usage + +1. Verify that the [requirements](/docs/api-gateway/consul-api-gateway-install#requirments) have been met. +1. Verify that the Consul API Gateway CRDs and controller have been installed and applied (see [Installation](/docs/api-gateway/consul-api-gateway-install)). +1. Configure the artifacts described below in [Configuration](/docs/api-gateway/configuration). + + + + ```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 + ``` + + + +## Common Error Messages + +Some of the errors messages commonly encountered during installation and operations of Consul API Gateway are listed below, along with suggested methods for resolving them. + +If the error message is not listed on this page, it may be listed on the main [Consul Common errors][consul-common-errors] page. If the error message is not listed on that page either, please consider following our general [Troubleshooting Guide][troubleshooting] or reach out to us in [Discuss](https://discuss.hashicorp.com/). + + + +### Helm installation failed: "no matches for kind" + +``` +Error: INSTALLATION FAILED: unable to build kubernetes objects from release manifest: [unable to recognize "": no matches for kind "GatewayClass" in version "gateway.networking.k8s.io/v1alpha2", unable to recognize "": no matches for kind "GatewayClassConfig" in version "api-gateway.consul.hashicorp.com/v1alpha1"] +``` +**Conditions:** +When this error occurs during the process of installing Consul API Gateway, it is usually caused by not having the required CRD files installed in Kubernetes prior to installing Consul API Gateway. + +**Impact:** +The installation process will typically fail after this error message is generated + +**Recommended Action:** +Install the required CRDs by using the command in Step 1 of the [Consul API Gateway installation instructions](/docs/api-gateway/consul-api-gateway-install) and then retry installing Consul API Gateway. + diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 3785b41823..2e312545b1 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -385,17 +385,43 @@ "title": "Installation", "path": "api-gateway/consul-api-gateway-install" }, - { - "title": "Technical Specifications", - "path": "api-gateway/tech-specs" - }, - { - "title": "Common Errors", - "path": "api-gateway/common-errors" - }, { "title": "Upgrades", - "path": "api-gateway/upgrade-specific-versions" + "path": "api-gateway/upgrades" + }, + { + "title": "Usage", + "routes": [ + { + "title": "Basic Usage", + "path": "api-gateway/usage/basic-usage" + } + ] + }, + { + "title": "Configuration", + "routes": [ + { + "title": "Overview", + "path": "api-gateway/configuration" + }, + { + "title": "Gateway", + "path": "api-gateway/configuration/gateway" + }, + { + "title": "Gateway Class", + "path": "api-gateway/configuration/gatewayclass" + }, + { + "title": "Gateway Class", + "path": "api-gateway/configuration/gatewayclassconfig" + }, + { + "title": "Gateway Class", + "path": "api-gateway/configuration/routes" + } + ] } ] }, From 96ef69ffb4a1a2fabdea0cbf8514a706c032d626 Mon Sep 17 00:00:00 2001 From: Sarah Alsmiller Date: Wed, 6 Jul 2022 09:52:58 -0500 Subject: [PATCH 002/124] delete extra file --- .../docs/api-gateway/common-errors.mdx | 67 ------------------- 1 file changed, 67 deletions(-) delete mode 100644 website/content/docs/api-gateway/common-errors.mdx diff --git a/website/content/docs/api-gateway/common-errors.mdx b/website/content/docs/api-gateway/common-errors.mdx deleted file mode 100644 index f49c9fefc5..0000000000 --- a/website/content/docs/api-gateway/common-errors.mdx +++ /dev/null @@ -1,67 +0,0 @@ ---- -layout: docs -page_title: Common Error Messages ---- - -# Common Error Messages - -Some of the errors messages commonly encountered during installation and operations of Consul API Gateway are listed below, along with suggested methods for resolving them. - -If the error message is not listed on this page, it may be listed on the main [Consul Common errors][consul-common-errors] page. If the error message is not listed on that page either, please consider following our general [Troubleshooting Guide][troubleshooting] or reach out to us in [Discuss](https://discuss.hashicorp.com/). - - - -### Helm installation failed: "no matches for kind" - -``` -Error: INSTALLATION FAILED: unable to build kubernetes objects from release manifest: [unable to recognize "": no matches for kind "GatewayClass" in version "gateway.networking.k8s.io/v1alpha2", unable to recognize "": no matches for kind "GatewayClassConfig" in version "api-gateway.consul.hashicorp.com/v1alpha1"] -``` -**Conditions:** -When this error occurs during the process of installing Consul API Gateway, it is usually caused by not having the required CRD files installed in Kubernetes prior to installing Consul API Gateway. - -**Impact:** -The installation process will typically fail after this error message is generated - -**Recommended Action:** -Install the required CRDs by using the command in Step 1 of the [Consul API Gateway installation instructions][install-instructions] and then retry installing Consul API Gateway. - - - - - -[consul-common-errors]: /docs/troubleshoot/common-errors -[troubleshooting]: https://learn.hashicorp.com/consul/day-2-operations/advanced-operations/troubleshooting -[install-instructions]: /docs/api-gateway/consul-api-gateway-install#installation \ No newline at end of file From ef36a80ebf6f32dc47b10bb6a358e63952f5509e Mon Sep 17 00:00:00 2001 From: Sarah Alsmiller Date: Wed, 6 Jul 2022 11:59:40 -0500 Subject: [PATCH 003/124] fix render issue --- website/content/docs/api-gateway/configuration/gateway.mdx | 2 +- .../content/docs/api-gateway/configuration/gatewayclass.mdx | 2 +- .../docs/api-gateway/configuration/gatewayclassconfig.mdx | 2 +- website/content/docs/api-gateway/configuration/index.mdx | 2 +- website/content/docs/api-gateway/configuration/routes.mdx | 2 +- website/data/docs-nav-data.json | 4 ++-- 6 files changed, 7 insertions(+), 7 deletions(-) diff --git a/website/content/docs/api-gateway/configuration/gateway.mdx b/website/content/docs/api-gateway/configuration/gateway.mdx index c1dd183268..5300fe7ca9 100644 --- a/website/content/docs/api-gateway/configuration/gateway.mdx +++ b/website/content/docs/api-gateway/configuration/gateway.mdx @@ -2,7 +2,7 @@ layout: docs page_title: Consul API Gateway Gateway description: >- -Consul API Gateway Gateway + Consul API Gateway Gateway --- # Gateway diff --git a/website/content/docs/api-gateway/configuration/gatewayclass.mdx b/website/content/docs/api-gateway/configuration/gatewayclass.mdx index 2a80fb683d..5f92df12dd 100644 --- a/website/content/docs/api-gateway/configuration/gatewayclass.mdx +++ b/website/content/docs/api-gateway/configuration/gatewayclass.mdx @@ -2,7 +2,7 @@ layout: docs page_title: Consul API Gateway GatewayClass description: >- -Consul API Gateway GatewayClass + Consul API Gateway GatewayClass --- # GatewayClass diff --git a/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx b/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx index 7648b04736..3d660d1a7c 100644 --- a/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx +++ b/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx @@ -2,7 +2,7 @@ layout: docs page_title: Consul API Gateway GatewayClassConfig description: >- -Consul API Gateway GatewayClassConfig + Consul API Gateway GatewayClassConfig --- # GatewayClassConfig diff --git a/website/content/docs/api-gateway/configuration/index.mdx b/website/content/docs/api-gateway/configuration/index.mdx index ebdaaeb6fa..8952a0dc4a 100644 --- a/website/content/docs/api-gateway/configuration/index.mdx +++ b/website/content/docs/api-gateway/configuration/index.mdx @@ -2,7 +2,7 @@ layout: docs page_title: Consul API Gateway Configuration description: >- -Consul API Gateway Configuration + Consul API Gateway Configuration --- # Configuration diff --git a/website/content/docs/api-gateway/configuration/routes.mdx b/website/content/docs/api-gateway/configuration/routes.mdx index 987e8193ab..32d314cec1 100644 --- a/website/content/docs/api-gateway/configuration/routes.mdx +++ b/website/content/docs/api-gateway/configuration/routes.mdx @@ -2,7 +2,7 @@ layout: docs page_title: Consul API Gateway Routes description: >- -Consul API Gateway Routes + Consul API Gateway Routes --- # Route diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index a8ef09cef5..148d54f68c 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -431,11 +431,11 @@ "path": "api-gateway/configuration/gatewayclass" }, { - "title": "Gateway Class", + "title": "Gateway Class Config", "path": "api-gateway/configuration/gatewayclassconfig" }, { - "title": "Gateway Class", + "title": "Routes", "path": "api-gateway/configuration/routes" } ] From 7a8da641c3032776c22d239ec2cd6f2cf74a5b64 Mon Sep 17 00:00:00 2001 From: Sarah Alsmiller Date: Wed, 6 Jul 2022 15:38:49 -0500 Subject: [PATCH 004/124] fix render issue --- website/content/docs/api-gateway/usage/basic-usage.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/usage/basic-usage.mdx b/website/content/docs/api-gateway/usage/basic-usage.mdx index 1eae64c4e5..9333df2130 100644 --- a/website/content/docs/api-gateway/usage/basic-usage.mdx +++ b/website/content/docs/api-gateway/usage/basic-usage.mdx @@ -2,7 +2,7 @@ layout: docs page_title: Consul API Gateway Basic Usage description: >- -Consul API Gateway Basic Usage + Consul API Gateway Basic Usage --- From d9f0a98121b3f4398dedeaf62a5b1b1bced5ebfd Mon Sep 17 00:00:00 2001 From: sarahalsmiller <100602640+sarahalsmiller@users.noreply.github.com> Date: Thu, 7 Jul 2022 15:21:40 -0500 Subject: [PATCH 005/124] Update website/content/docs/api-gateway/configuration/gateway.mdx Co-authored-by: Nathan Coleman --- website/content/docs/api-gateway/configuration/gateway.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/configuration/gateway.mdx b/website/content/docs/api-gateway/configuration/gateway.mdx index 5300fe7ca9..8ff46ef827 100644 --- a/website/content/docs/api-gateway/configuration/gateway.mdx +++ b/website/content/docs/api-gateway/configuration/gateway.mdx @@ -167,7 +167,7 @@ Allowed values `TCP`, `HTTP`, `HTTPS` * Required: optional ## Complete configuration -The following example shows a fully configured Gateway. +The following example shows a fully configured `Gateway`. ```yaml kind: Gateway From 7f28c388ba29d5343d0ba85114c0bf1febc8e00f Mon Sep 17 00:00:00 2001 From: sarahalsmiller <100602640+sarahalsmiller@users.noreply.github.com> Date: Thu, 7 Jul 2022 15:21:45 -0500 Subject: [PATCH 006/124] Update website/content/docs/api-gateway/configuration/gateway.mdx Co-authored-by: Nathan Coleman --- website/content/docs/api-gateway/configuration/gateway.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/configuration/gateway.mdx b/website/content/docs/api-gateway/configuration/gateway.mdx index 8ff46ef827..e82fb8b462 100644 --- a/website/content/docs/api-gateway/configuration/gateway.mdx +++ b/website/content/docs/api-gateway/configuration/gateway.mdx @@ -156,7 +156,7 @@ Allowed values `TCP`, `HTTP`, `HTTPS` ### listeners.tls.certificateRefs `CertificateRefs` contains a series of references to Kubernetes objects that contains TLS certificates and private keys. These certificates are used to establish a TLS handshake for requests that match the hostname of the associated `listener`. Each reference must be a Kubernetes Secret, and, if using a Secret in a namespace other than the`Gateway`'s, must have a corresponding `ReferencePolicy` created. * Type: Object or Array -* Required: required if tls is set +* Required: required if `tls` is set ### listeners.tls.mode * Type: String From 446c6dff31bb5ab59d701596bcb5d3b3025c55c3 Mon Sep 17 00:00:00 2001 From: sarahalsmiller <100602640+sarahalsmiller@users.noreply.github.com> Date: Thu, 7 Jul 2022 15:22:26 -0500 Subject: [PATCH 007/124] Update website/content/docs/api-gateway/configuration/gateway.mdx Co-authored-by: Nathan Coleman --- website/content/docs/api-gateway/configuration/gateway.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/configuration/gateway.mdx b/website/content/docs/api-gateway/configuration/gateway.mdx index e82fb8b462..0d9b4cd050 100644 --- a/website/content/docs/api-gateway/configuration/gateway.mdx +++ b/website/content/docs/api-gateway/configuration/gateway.mdx @@ -53,7 +53,7 @@ Specify the following parameters to declare a Gateway: ## Specification -This topic provides details about the configuration parameters +This topic provides details about the configuration parameters. ### gatewayClassName Specifies the name of the `GatewayClass` resource used for the `Gateway` instance. From bf53a73dde9fae4e4743df8ec9ba29337c346ea8 Mon Sep 17 00:00:00 2001 From: sarahalsmiller <100602640+sarahalsmiller@users.noreply.github.com> Date: Thu, 7 Jul 2022 15:22:39 -0500 Subject: [PATCH 008/124] Update website/content/docs/api-gateway/configuration/gateway.mdx Co-authored-by: Nathan Coleman --- website/content/docs/api-gateway/configuration/gateway.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/website/content/docs/api-gateway/configuration/gateway.mdx b/website/content/docs/api-gateway/configuration/gateway.mdx index 0d9b4cd050..b217f92903 100644 --- a/website/content/docs/api-gateway/configuration/gateway.mdx +++ b/website/content/docs/api-gateway/configuration/gateway.mdx @@ -82,9 +82,9 @@ This parameter has the following properties: * Required: required You can specify one of the following strings: -* All: Routes in all namespaces may be attached to the Gateway. -* Same: Only routes in the same namespace as the Gateway may be attached. -* Selector: Only routes in namespaces that match the selector configuration may be attached. +* `All`: Routes in all namespaces may be attached to the `Gateway`. +* `Same`: Only routes in the same namespace as the `Gateway` may be attached. +* `Selector`: Only routes in namespaces that match the `selector` may be attached. ### listeners.allowedRoutes.namespaces.selector The `selector` configuration matches zero or more namespaces that determine which routes are allowed to attach to the listener. From e305fb232db74067ae0338cdaa6fa656b065d20f Mon Sep 17 00:00:00 2001 From: sarahalsmiller <100602640+sarahalsmiller@users.noreply.github.com> Date: Thu, 7 Jul 2022 15:22:47 -0500 Subject: [PATCH 009/124] Update website/content/docs/api-gateway/configuration/gateway.mdx Co-authored-by: Nathan Coleman --- website/content/docs/api-gateway/configuration/gateway.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/configuration/gateway.mdx b/website/content/docs/api-gateway/configuration/gateway.mdx index b217f92903..4d6e27c3bf 100644 --- a/website/content/docs/api-gateway/configuration/gateway.mdx +++ b/website/content/docs/api-gateway/configuration/gateway.mdx @@ -133,7 +133,7 @@ Specifies the `listeners` hostname * Required: required ### listeners.name -Specifies the `listeners` name +Specifies the `listener`'s name * Type: string * Required: required From 396a75ff06bc254b5baca0c917f2c8ecd1f1b5fd Mon Sep 17 00:00:00 2001 From: sarahalsmiller <100602640+sarahalsmiller@users.noreply.github.com> Date: Thu, 7 Jul 2022 15:22:52 -0500 Subject: [PATCH 010/124] Update website/content/docs/api-gateway/configuration/gateway.mdx Co-authored-by: Nathan Coleman --- website/content/docs/api-gateway/configuration/gateway.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/configuration/gateway.mdx b/website/content/docs/api-gateway/configuration/gateway.mdx index 4d6e27c3bf..226e368e64 100644 --- a/website/content/docs/api-gateway/configuration/gateway.mdx +++ b/website/content/docs/api-gateway/configuration/gateway.mdx @@ -151,7 +151,7 @@ Allowed values `TCP`, `HTTP`, `HTTPS` ### listeners.tls * Type: Object -* Required: required if protocol is set to HTTPS +* Required: required if `protocol` is set to `HTTPS` ### listeners.tls.certificateRefs `CertificateRefs` contains a series of references to Kubernetes objects that contains TLS certificates and private keys. These certificates are used to establish a TLS handshake for requests that match the hostname of the associated `listener`. Each reference must be a Kubernetes Secret, and, if using a Secret in a namespace other than the`Gateway`'s, must have a corresponding `ReferencePolicy` created. From 7bb6e8379ae301b4fcc29b3432b05bd4f2f9ae6a Mon Sep 17 00:00:00 2001 From: sarahalsmiller <100602640+sarahalsmiller@users.noreply.github.com> Date: Thu, 7 Jul 2022 15:23:03 -0500 Subject: [PATCH 011/124] Update website/content/docs/api-gateway/configuration/gateway.mdx Co-authored-by: Nathan Coleman --- website/content/docs/api-gateway/configuration/gateway.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/configuration/gateway.mdx b/website/content/docs/api-gateway/configuration/gateway.mdx index 226e368e64..6d3d1706f2 100644 --- a/website/content/docs/api-gateway/configuration/gateway.mdx +++ b/website/content/docs/api-gateway/configuration/gateway.mdx @@ -147,7 +147,7 @@ Specifies the protocol the `listener` will use * Type: string * Required: required -Allowed values `TCP`, `HTTP`, `HTTPS` +Allowed values are `TCP`, `HTTP`, or `HTTPS` ### listeners.tls * Type: Object From 8a5b597afefc90c60737896ec8fe5177a5e07db0 Mon Sep 17 00:00:00 2001 From: sarahalsmiller <100602640+sarahalsmiller@users.noreply.github.com> Date: Thu, 7 Jul 2022 15:23:13 -0500 Subject: [PATCH 012/124] Update website/content/docs/api-gateway/configuration/gateway.mdx Co-authored-by: Nathan Coleman --- website/content/docs/api-gateway/configuration/gateway.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/content/docs/api-gateway/configuration/gateway.mdx b/website/content/docs/api-gateway/configuration/gateway.mdx index 6d3d1706f2..e526ec000e 100644 --- a/website/content/docs/api-gateway/configuration/gateway.mdx +++ b/website/content/docs/api-gateway/configuration/gateway.mdx @@ -92,8 +92,8 @@ The `selector` configuration matches zero or more namespaces that determine whic * Required: Required when from is configured to selector. The selector configuration contains one of the following objects: -* matchExpressions -* matchLabels +* `matchExpressions` +* `matchLabels` ### listeners.allowedRoutes.namespaces.selector.matchExpressions 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: From 8fbb040e826e85b6e46099edb60b44f32e9199b8 Mon Sep 17 00:00:00 2001 From: sarahalsmiller <100602640+sarahalsmiller@users.noreply.github.com> Date: Thu, 7 Jul 2022 15:23:22 -0500 Subject: [PATCH 013/124] Update website/content/docs/api-gateway/configuration/gateway.mdx Co-authored-by: Nathan Coleman --- website/content/docs/api-gateway/configuration/gateway.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/configuration/gateway.mdx b/website/content/docs/api-gateway/configuration/gateway.mdx index e526ec000e..9ef573435d 100644 --- a/website/content/docs/api-gateway/configuration/gateway.mdx +++ b/website/content/docs/api-gateway/configuration/gateway.mdx @@ -89,7 +89,7 @@ You can specify one of the following strings: ### listeners.allowedRoutes.namespaces.selector The `selector` configuration matches zero or more namespaces that determine which routes are allowed to attach to the listener. * Type: Object -* Required: Required when from is configured to selector. +* Required: Required when `from` is configured to `Selector`. The selector configuration contains one of the following objects: * `matchExpressions` From a384d0d6676d5337923679bf59bf576142b9975d Mon Sep 17 00:00:00 2001 From: sarahalsmiller <100602640+sarahalsmiller@users.noreply.github.com> Date: Thu, 7 Jul 2022 15:23:46 -0500 Subject: [PATCH 014/124] Update website/content/docs/api-gateway/configuration/gateway.mdx Co-authored-by: Nathan Coleman --- website/content/docs/api-gateway/configuration/gateway.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/configuration/gateway.mdx b/website/content/docs/api-gateway/configuration/gateway.mdx index 9ef573435d..be27c7178c 100644 --- a/website/content/docs/api-gateway/configuration/gateway.mdx +++ b/website/content/docs/api-gateway/configuration/gateway.mdx @@ -87,7 +87,7 @@ You can specify one of the following strings: * `Selector`: Only routes in namespaces that match the `selector` may be attached. ### listeners.allowedRoutes.namespaces.selector -The `selector` configuration matches zero or more namespaces that determine which routes are allowed to attach to the listener. +Specifies a method of matching namespaces from which routes are allowed to attach to the listener. * Type: Object * Required: Required when `from` is configured to `Selector`. From 50cc6067e9dd27c2db597c1ef3183686bc1f4294 Mon Sep 17 00:00:00 2001 From: sarahalsmiller <100602640+sarahalsmiller@users.noreply.github.com> Date: Fri, 8 Jul 2022 09:54:47 -0500 Subject: [PATCH 015/124] Update website/content/docs/api-gateway/configuration/gateway.mdx Co-authored-by: Nathan Coleman --- website/content/docs/api-gateway/configuration/gateway.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/configuration/gateway.mdx b/website/content/docs/api-gateway/configuration/gateway.mdx index be27c7178c..c99763bae2 100644 --- a/website/content/docs/api-gateway/configuration/gateway.mdx +++ b/website/content/docs/api-gateway/configuration/gateway.mdx @@ -128,7 +128,7 @@ namespaceSelector: For more on labels, see [Labels and Selectors](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) ### listeners.hostname -Specifies the `listeners` hostname +Specifies the `listener`'s hostname * Type: string * Required: required From f076c8086dad6f44193d3c0af0d2998dd52fe7c6 Mon Sep 17 00:00:00 2001 From: sarahalsmiller <100602640+sarahalsmiller@users.noreply.github.com> Date: Wed, 13 Jul 2022 16:01:45 -0500 Subject: [PATCH 016/124] Update website/content/docs/api-gateway/configuration/gatewayclass.mdx Co-authored-by: Nathan Coleman --- .../docs/api-gateway/configuration/gatewayclass.mdx | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/website/content/docs/api-gateway/configuration/gatewayclass.mdx b/website/content/docs/api-gateway/configuration/gatewayclass.mdx index 5f92df12dd..1988c9a324 100644 --- a/website/content/docs/api-gateway/configuration/gatewayclass.mdx +++ b/website/content/docs/api-gateway/configuration/gatewayclass.mdx @@ -22,14 +22,13 @@ The following example creates a gateway class called `test-gateway-class`: apiVersion: gateway.networking.k8s.io/v1alpha2 kind: GatewayClass metadata: - name: test-gateway-class + 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 - ``` + controllerName: 'hashicorp.com/consul-api-gateway-controller' + parametersRef: + group: api-gateway.consul.hashicorp.com + kind: GatewayClassConfig + name: test-gateway-class-config From 8cd1ff2d24bc552363fe9ddb4c04cc4dee155ddb Mon Sep 17 00:00:00 2001 From: sarahalsmiller <100602640+sarahalsmiller@users.noreply.github.com> Date: Wed, 13 Jul 2022 16:01:53 -0500 Subject: [PATCH 017/124] Update website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx Co-authored-by: Nathan Coleman --- .../configuration/gatewayclassconfig.mdx | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx b/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx index 3d660d1a7c..ed416430df 100644 --- a/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx +++ b/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx @@ -18,16 +18,15 @@ The following example creates a gateway class configuration called `test-gateway apiVersion: api-gateway.consul.hashicorp.com/v1alpha1 kind: GatewayClassConfig metadata: - name: test-gateway-class-config + name: test-gateway-class-config spec: - useHostPorts: true - logLevel: 'trace' - consul: - scheme: 'https' - ports: - http: 8501 - grpc: 8502 - ``` + useHostPorts: true + logLevel: 'trace' + consul: + scheme: 'https' + ports: + http: 8501 + grpc: 8502 From 45467e141b8c55db8db9180725d668f617ba0a20 Mon Sep 17 00:00:00 2001 From: sarahalsmiller <100602640+sarahalsmiller@users.noreply.github.com> Date: Wed, 13 Jul 2022 16:18:39 -0500 Subject: [PATCH 018/124] Update website/content/docs/api-gateway/usage/basic-usage.mdx Co-authored-by: Nathan Coleman --- website/content/docs/api-gateway/usage/basic-usage.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/usage/basic-usage.mdx b/website/content/docs/api-gateway/usage/basic-usage.mdx index 9333df2130..92e7829c73 100644 --- a/website/content/docs/api-gateway/usage/basic-usage.mdx +++ b/website/content/docs/api-gateway/usage/basic-usage.mdx @@ -25,7 +25,7 @@ description: >- 1. Issue the `kubectl apply` command to implement the configurations, e.g.: ```shell-session -$ kubectl apply -f gateway.yaml routes.yaml +$ kubectl apply --filename gateway.yaml routes.yaml ``` -## Common Error Messages - -Some of the errors messages commonly encountered during installation and operations of Consul API Gateway are listed below, along with suggested methods for resolving them. +## Error Messages If the error message is not listed on this page, it may be listed on the main [Consul Common errors][consul-common-errors] page. If the error message is not listed on that page either, please consider following our general [Troubleshooting Guide][troubleshooting] or reach out to us in [Discuss](https://discuss.hashicorp.com/). From 381a987549a6e27a6cce0cffc2254f13ea0124bd Mon Sep 17 00:00:00 2001 From: sarahalsmiller <100602640+sarahalsmiller@users.noreply.github.com> Date: Wed, 20 Jul 2022 16:02:20 -0500 Subject: [PATCH 029/124] Update website/content/docs/api-gateway/usage/basic-usage.mdx Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> --- website/content/docs/api-gateway/usage/basic-usage.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/usage/basic-usage.mdx b/website/content/docs/api-gateway/usage/basic-usage.mdx index 9243e66520..7576cd26aa 100644 --- a/website/content/docs/api-gateway/usage/basic-usage.mdx +++ b/website/content/docs/api-gateway/usage/basic-usage.mdx @@ -10,7 +10,7 @@ description: >- 1. Verify that the [requirements](/docs/api-gateway/consul-api-gateway-install#requirments) have been met. 1. Verify that the Consul API Gateway CRDs and controller have been installed and applied (see [Installation](/docs/api-gateway/consul-api-gateway-install)). -1. Configure the artifacts described below in [Configuration](/docs/api-gateway/configuration). +1. Configure the artifacts as describe in the [Configuration](/docs/api-gateway/configuration) section. From f1a6067a0be7e383d3be93e1c7c5f28802e10186 Mon Sep 17 00:00:00 2001 From: sarahalsmiller <100602640+sarahalsmiller@users.noreply.github.com> Date: Wed, 20 Jul 2022 16:03:56 -0500 Subject: [PATCH 030/124] Update website/data/docs-nav-data.json Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> --- website/data/docs-nav-data.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 1ce60ffc9a..786a095315 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -431,11 +431,11 @@ "path": "api-gateway/configuration/gateway" }, { - "title": "Gateway Class", + "title": "GatewayClass", "path": "api-gateway/configuration/gatewayclass" }, { - "title": "Gateway Class Config", + "title": "GatewayClassConfig", "path": "api-gateway/configuration/gatewayclassconfig" }, { From c859af7ad951ba5024d0ea94492a4fcbb236283a Mon Sep 17 00:00:00 2001 From: sarahalsmiller <100602640+sarahalsmiller@users.noreply.github.com> Date: Wed, 20 Jul 2022 16:04:53 -0500 Subject: [PATCH 031/124] Update website/content/docs/api-gateway/install.mdx Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> --- website/content/docs/api-gateway/install.mdx | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/website/content/docs/api-gateway/install.mdx b/website/content/docs/api-gateway/install.mdx index 298366ef4c..54dd1d6e1a 100644 --- a/website/content/docs/api-gateway/install.mdx +++ b/website/content/docs/api-gateway/install.mdx @@ -23,7 +23,8 @@ Ensure that the environment you are deploying Consul API Gateway in meets the re $ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?ref=vVERSION" ``` -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. Available versions of the [Consul](https://hub.docker.com/r/hashicorp/consul/tags) and [Consul API Gateway](https://hub.docker.com/r/hashicorp/consul-api-gateway/tags) Docker images can be found on DockerHub, with additional context on version compatibility published in [GitHub releases](https://github.com/hashicorp/consul-api-gateway/releases). 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. +1. Create a `values.yaml` file for your Consul API Gateway deployment. +1. Copy the following example configuration into the `values.yaml` file. The Consul Helm chart uses the `values.yaml` file to install Consul. @@ -37,10 +38,11 @@ Ensure that the environment you are deploying Consul API Gateway in meets the re apiGateway: enabled: true image: hashicorp/consul-api-gateway:VERSION - ``` + ``` - + + Refer to the [Consul](https://hub.docker.com/r/hashicorp/consul/tags) and [Consul API Gateway] (https://hub.docker.com/r/hashicorp/consul-api-gateway/tags) DockerHub pages for information about all available versions, as well as additional context about version compatibility published in [GitHub releases](https://github.com/hashicorp/consul-api-gateway/releases). 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. 1. Install Consul API Gateway using the standard Consul Helm chart and specify the custom values file. Available versions of the [Consul Helm chart](https://github.com/hashicorp/consul-k8s/releases) can be found in GitHub releases. ```shell-session From 7cbc1d91382505f143223296c3fe94aa5b973768 Mon Sep 17 00:00:00 2001 From: Sarah Alsmiller Date: Wed, 20 Jul 2022 16:21:14 -0500 Subject: [PATCH 032/124] fix indent issue --- .../docs/api-gateway/configuration/routes.mdx | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/website/content/docs/api-gateway/configuration/routes.mdx b/website/content/docs/api-gateway/configuration/routes.mdx index 32d314cec1..13e720f56e 100644 --- a/website/content/docs/api-gateway/configuration/routes.mdx +++ b/website/content/docs/api-gateway/configuration/routes.mdx @@ -23,15 +23,15 @@ The following example creates a route named `example-route` associated with a li apiVersion: gateway.networking.k8s.io/v1alpha2 kind: HTTPRoute metadata: - name: example-route + name: example-route spec: - parentRefs: - - name: example-gateway - rules: - - backendRefs: - - kind: Service - name: echo - port: 8080 + parentRefs: + - name: example-gateway + rules: + - backendRefs: + - kind: Service + name: echo + port: 8080 ``` From 9feb465f62f8f4767e9488e225ae91e44ed06e0c Mon Sep 17 00:00:00 2001 From: sarahalsmiller <100602640+sarahalsmiller@users.noreply.github.com> Date: Thu, 21 Jul 2022 14:39:25 -0500 Subject: [PATCH 033/124] Update website/content/docs/api-gateway/configuration/gateway.mdx Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> --- website/content/docs/api-gateway/configuration/gateway.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/configuration/gateway.mdx b/website/content/docs/api-gateway/configuration/gateway.mdx index 635843d4ba..f88ac19335 100644 --- a/website/content/docs/api-gateway/configuration/gateway.mdx +++ b/website/content/docs/api-gateway/configuration/gateway.mdx @@ -21,7 +21,7 @@ Specify the following parameters to declare a Gateway: |:-----------:|:----------------------------------------------------------------------------------------------------------------------------------------------------------:|:--------:| | `kind` | Specifies the type of configuration object. The value should always be Gateway | Required | | `description` | Human-readable string for describing the purpose of the Gateway. | Optional | -| `version ` | Specifies the Kubernetes API version. The value should always be gateway.networking.k8s.io/v1alpha2 | Required | +| `version ` | Specifies the Kubernetes API version. The value should always be `gateway.networking.k8s.io/v1alpha2` | Required | | `scope` | Specifies the effective scope of the Gateway. The value should always be namespaced. | Required | | `fields` | Specifies the configurations for the Gateway. The fields are listed in the Configuration model. Details for each field are described in the Specification. | Required | From dfc9ae4a609b3cfbfa141c65865fc604d29dcc93 Mon Sep 17 00:00:00 2001 From: sarahalsmiller <100602640+sarahalsmiller@users.noreply.github.com> Date: Thu, 21 Jul 2022 14:39:34 -0500 Subject: [PATCH 034/124] Update website/content/docs/api-gateway/configuration/gateway.mdx Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> --- website/content/docs/api-gateway/configuration/gateway.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/configuration/gateway.mdx b/website/content/docs/api-gateway/configuration/gateway.mdx index f88ac19335..affe2cb5fc 100644 --- a/website/content/docs/api-gateway/configuration/gateway.mdx +++ b/website/content/docs/api-gateway/configuration/gateway.mdx @@ -20,7 +20,7 @@ Specify the following parameters to declare a Gateway: | Parameter | Description | Required | |:-----------:|:----------------------------------------------------------------------------------------------------------------------------------------------------------:|:--------:| | `kind` | Specifies the type of configuration object. The value should always be Gateway | Required | -| `description` | Human-readable string for describing the purpose of the Gateway. | Optional | +| `description` | Human-readable string that describes the purpose of the `Gateway`. | Optional | | `version ` | Specifies the Kubernetes API version. The value should always be `gateway.networking.k8s.io/v1alpha2` | Required | | `scope` | Specifies the effective scope of the Gateway. The value should always be namespaced. | Required | | `fields` | Specifies the configurations for the Gateway. The fields are listed in the Configuration model. Details for each field are described in the Specification. | Required | From 5d02480430026905565c89ee96f4789df5dc3f7e Mon Sep 17 00:00:00 2001 From: sarahalsmiller <100602640+sarahalsmiller@users.noreply.github.com> Date: Thu, 21 Jul 2022 14:39:47 -0500 Subject: [PATCH 035/124] Update website/content/docs/api-gateway/configuration/gateway.mdx Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> --- website/content/docs/api-gateway/configuration/gateway.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/configuration/gateway.mdx b/website/content/docs/api-gateway/configuration/gateway.mdx index affe2cb5fc..be1de030b7 100644 --- a/website/content/docs/api-gateway/configuration/gateway.mdx +++ b/website/content/docs/api-gateway/configuration/gateway.mdx @@ -19,7 +19,7 @@ Specify the following parameters to declare a Gateway: | Parameter | Description | Required | |:-----------:|:----------------------------------------------------------------------------------------------------------------------------------------------------------:|:--------:| -| `kind` | Specifies the type of configuration object. The value should always be Gateway | Required | +| `kind` | Specifies the type of configuration object. The value should always be `Gateway`. | Required | | `description` | Human-readable string that describes the purpose of the `Gateway`. | Optional | | `version ` | Specifies the Kubernetes API version. The value should always be `gateway.networking.k8s.io/v1alpha2` | Required | | `scope` | Specifies the effective scope of the Gateway. The value should always be namespaced. | Required | From c54e0904ded357fd27dd7d1f2a64472e70c6220e Mon Sep 17 00:00:00 2001 From: sarahalsmiller <100602640+sarahalsmiller@users.noreply.github.com> Date: Thu, 21 Jul 2022 14:39:55 -0500 Subject: [PATCH 036/124] Update website/content/docs/api-gateway/configuration/gateway.mdx Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> --- website/content/docs/api-gateway/configuration/gateway.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/configuration/gateway.mdx b/website/content/docs/api-gateway/configuration/gateway.mdx index be1de030b7..2829ef03eb 100644 --- a/website/content/docs/api-gateway/configuration/gateway.mdx +++ b/website/content/docs/api-gateway/configuration/gateway.mdx @@ -18,7 +18,7 @@ Gateway instances derive their configurations from the [`GatewayClass`](/docs/ap Specify the following parameters to declare a Gateway: | Parameter | Description | Required | -|:-----------:|:----------------------------------------------------------------------------------------------------------------------------------------------------------:|:--------:| +| -----------:|:----------------------------------------------------------------------------------------------------------------------------------------------------------:|:--------:| | `kind` | Specifies the type of configuration object. The value should always be `Gateway`. | Required | | `description` | Human-readable string that describes the purpose of the `Gateway`. | Optional | | `version ` | Specifies the Kubernetes API version. The value should always be `gateway.networking.k8s.io/v1alpha2` | Required | From 20e97a7729bf8de9c7f3be5fee44519a361775d7 Mon Sep 17 00:00:00 2001 From: Sarah Alsmiller Date: Thu, 21 Jul 2022 14:53:55 -0500 Subject: [PATCH 037/124] merge back in mike's environment doc in install --- website/content/docs/api-gateway/install.mdx | 52 +++++++++++--------- 1 file changed, 28 insertions(+), 24 deletions(-) diff --git a/website/content/docs/api-gateway/install.mdx b/website/content/docs/api-gateway/install.mdx index 54dd1d6e1a..11ee46f1f6 100644 --- a/website/content/docs/api-gateway/install.mdx +++ b/website/content/docs/api-gateway/install.mdx @@ -15,39 +15,43 @@ Ensure that the environment you are deploying Consul API Gateway in meets the re ## Installation --> **Version reference convention:** Replace `VERSION` in command and configuration examples with the Consul API Gateway version you are installing, such as `0.3.0`. In some instances, `VERSION` is prepended with a lowercase _v_. This indicates that you must include the `v` as is part of the version, for example `v0.3.0`. +1. Set the version of Consul API Gateway you are installing as an environment variable. The following steps use this environment variable in commands and configurations. + +```shell-session +$ export VERSION=0.3.0 +``` 1. Issue the following command to install the CRDs: - ```shell-session - $ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?ref=vVERSION" - ``` +```shell-session +$ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?ref=v$VERSION" +``` -1. Create a `values.yaml` file for your Consul API Gateway deployment. -1. Copy the following example configuration into the `values.yaml` file. The Consul Helm chart uses the `values.yaml` file to install Consul. +1. Create a `values.yaml` file for your Consul API Gateway deployment by copying the following content and running it in the environment where you set the `VERSION` environment variable. The Consul Helm chart uses this `values.yaml` file to deploy the API Gateway. Available versions of the [Consul](https://hub.docker.com/r/hashicorp/consul/tags) and [Consul API Gateway](https://hub.docker.com/r/hashicorp/consul-api-gateway/tags) Docker images can be found on DockerHub, with additional context on version compatibility published in [GitHub releases](https://github.com/hashicorp/consul-api-gateway/releases). For more options to configure your Consul API Gateway deployment through the Helm chart, refer to [Helm Chart Configuration - apiGateway](https://www.consul.io/docs/k8s/helm#apigateway). - + - ```yaml - global: - name: consul - connectInject: - enabled: true - controller: - enabled: true - apiGateway: - enabled: true - image: hashicorp/consul-api-gateway:VERSION - ``` + ```shell + cat < values.yaml + global: + name: consul + connectInject: + enabled: true + controller: + enabled: true + apiGateway: + enabled: true + image: hashicorp/consul-api-gateway:$VERSION + EOF + ``` + + - - - Refer to the [Consul](https://hub.docker.com/r/hashicorp/consul/tags) and [Consul API Gateway] (https://hub.docker.com/r/hashicorp/consul-api-gateway/tags) DockerHub pages for information about all available versions, as well as additional context about version compatibility published in [GitHub releases](https://github.com/hashicorp/consul-api-gateway/releases). 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. 1. Install Consul API Gateway using the standard Consul Helm chart and specify the custom values file. Available versions of the [Consul Helm chart](https://github.com/hashicorp/consul-k8s/releases) can be found in GitHub releases. - ```shell-session - $ helm install consul hashicorp/consul --version 0.45.0 --values values.yaml --create-namespace --namespace consul - ``` +```shell-session +$ helm install consul hashicorp/consul --version 0.45.0 --values values.yaml --create-namespace --namespace consul + ``` +[tech-specs]: /docs/api-gateway/tech-specs [rel-notes]: /docs/release-notes From 355f6dbd48680bf40c19e435c0fcb24f5a5f38ad Mon Sep 17 00:00:00 2001 From: sarahalsmiller <100602640+sarahalsmiller@users.noreply.github.com> Date: Fri, 22 Jul 2022 09:45:00 -0500 Subject: [PATCH 044/124] Update website/content/docs/api-gateway/usage/basic-usage.mdx Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> --- website/content/docs/api-gateway/usage/basic-usage.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/usage/basic-usage.mdx b/website/content/docs/api-gateway/usage/basic-usage.mdx index 7576cd26aa..d5cd194776 100644 --- a/website/content/docs/api-gateway/usage/basic-usage.mdx +++ b/website/content/docs/api-gateway/usage/basic-usage.mdx @@ -119,7 +119,7 @@ REPLACE THIS with the actions the user should take to try to correct the situati Error: INSTALLATION FAILED: unable to build kubernetes objects from release manifest: [unable to recognize "": no matches for kind "GatewayClass" in version "gateway.networking.k8s.io/v1alpha2", unable to recognize "": no matches for kind "GatewayClassConfig" in version "api-gateway.consul.hashicorp.com/v1alpha1"] ``` **Conditions:** -When this error occurs during the process of installing Consul API Gateway, it is usually caused by not having the required CRD files installed in Kubernetes prior to installing Consul API Gateway. +Consul API Gateway generates this error when the required CRD files have not been installed in Kubernetes prior to installing Consul API Gateway. **Impact:** The installation process typically fails after this error message is generated. From 082ad42ff43fe0dce13d0ab9dd85c47937afadaf Mon Sep 17 00:00:00 2001 From: Sarah Alsmiller Date: Fri, 22 Jul 2022 14:20:27 -0500 Subject: [PATCH 045/124] add redirects --- website/redirects.js | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/website/redirects.js b/website/redirects.js index c2f751df78..c25cf8ccc3 100644 --- a/website/redirects.js +++ b/website/redirects.js @@ -1319,4 +1319,14 @@ module.exports = [ destination: '/docs/k8s/installation/vault/data-integration/connect-ca', permanent: true, }, + { + source: '/docs/api-gateway/common-errors', + destination: '/docs/api-gateway/usage/basic-usage#Common_Error_Messages', + permanent: true, + }, + { + source: '/docs/api-gateway/upgrade-specific-versions', + destination: '/docs/api-gateway/upgrades', + permanent: true, + }, ] From af56187fb770809af4a0023b02a1660dcbf21f52 Mon Sep 17 00:00:00 2001 From: Sarah Alsmiller Date: Mon, 25 Jul 2022 20:30:51 -0500 Subject: [PATCH 046/124] left align table --- website/content/docs/api-gateway/configuration/gateway.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/content/docs/api-gateway/configuration/gateway.mdx b/website/content/docs/api-gateway/configuration/gateway.mdx index 2829ef03eb..fda00c9066 100644 --- a/website/content/docs/api-gateway/configuration/gateway.mdx +++ b/website/content/docs/api-gateway/configuration/gateway.mdx @@ -17,8 +17,8 @@ Gateway instances derive their configurations from the [`GatewayClass`](/docs/ap Specify the following parameters to declare a Gateway: -| Parameter | Description | Required | -| -----------:|:----------------------------------------------------------------------------------------------------------------------------------------------------------:|:--------:| +| Parameter | Description | Required | +| :----------- |:---------------------------------------------------------------------------------------------------------------------------------------------------------- |:-------- | | `kind` | Specifies the type of configuration object. The value should always be `Gateway`. | Required | | `description` | Human-readable string that describes the purpose of the `Gateway`. | Optional | | `version ` | Specifies the Kubernetes API version. The value should always be `gateway.networking.k8s.io/v1alpha2` | Required | From 8fe5c14d80b2e7326e79cad25d96ab6387c354f6 Mon Sep 17 00:00:00 2001 From: Sarah Alsmiller Date: Mon, 25 Jul 2022 21:57:30 -0500 Subject: [PATCH 047/124] 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. From fd9c4f7f6d620842c305b022368f4717643d258e Mon Sep 17 00:00:00 2001 From: sarahalsmiller <100602640+sarahalsmiller@users.noreply.github.com> Date: Tue, 26 Jul 2022 09:30:38 -0500 Subject: [PATCH 048/124] Update website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx Co-authored-by: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> --- .../docs/api-gateway/configuration/gatewayclassconfig.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx b/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx index 5b35c04aa7..33a7c5cad7 100644 --- a/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx +++ b/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx @@ -11,7 +11,7 @@ This topic provides full details about the `GatewayClassConfig` resource ## Introduction -The `GatewayClassConfig` object describes Consul API Gateway-related configuration parameters for the [`GatewayClass`](#gatewayclass). +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`. A `GatewayClassConfig` object provides configuration options specifc to Consul API Gateway From 8baaf2492a69ff9b1bc1fdf440680dc4effdfc65 Mon Sep 17 00:00:00 2001 From: Sarah Alsmiller Date: Tue, 26 Jul 2022 09:31:27 -0500 Subject: [PATCH 049/124] clean up extra sentence --- .../docs/api-gateway/configuration/gatewayclassconfig.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx b/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx index 33a7c5cad7..2abe3da45c 100644 --- a/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx +++ b/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx @@ -11,9 +11,7 @@ This topic provides full details about the `GatewayClassConfig` resource ## Introduction -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`. - -A `GatewayClassConfig` object provides configuration options specifc to Consul API Gateway +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 From 64da99a927ebc5b065da72a5f707e02906b8450e Mon Sep 17 00:00:00 2001 From: Sarah Alsmiller Date: Tue, 26 Jul 2022 09:33:15 -0500 Subject: [PATCH 050/124] clean up leftover table lines --- .../api-gateway/configuration/gatewayclassconfig.mdx | 9 --------- 1 file changed, 9 deletions(-) diff --git a/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx b/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx index 2abe3da45c..8a321be388 100644 --- a/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx +++ b/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx @@ -175,13 +175,4 @@ The following example creates a gateway class configuration called `test-gateway ``` - - - - | 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. From b69c3fb410770b59d5ef0f36febe6bfe517981f4 Mon Sep 17 00:00:00 2001 From: Sarah Alsmiller Date: Tue, 26 Jul 2022 10:10:17 -0500 Subject: [PATCH 051/124] restructure allowed values to be consistent --- .../api-gateway/configuration/gateway.mdx | 3 +-- .../configuration/gatewayclass.mdx | 14 ++++++++---- .../configuration/gatewayclassconfig.mdx | 22 +++++++++++++++++-- .../docs/api-gateway/configuration/index.mdx | 6 +++++ 4 files changed, 37 insertions(+), 8 deletions(-) diff --git a/website/content/docs/api-gateway/configuration/gateway.mdx b/website/content/docs/api-gateway/configuration/gateway.mdx index b340d3c329..d30123e09c 100644 --- a/website/content/docs/api-gateway/configuration/gateway.mdx +++ b/website/content/docs/api-gateway/configuration/gateway.mdx @@ -56,13 +56,12 @@ Specify the following parameters to declare a Gateway: This topic provides details about the configuration parameters. ### gatewayClassName -Specifies the name of the [`GatewayClass`](/docs/api-gateway/configuration/gatewayclass) resource used for the `Gateway` instance. +Specifies the name of the [`GatewayClass`](/docs/api-gateway/configuration/gatewayclass) resource used for the `Gateway` instance. Unless a custom [GatewayClass](/docs/api-gateway/configuration/gatewayclass) is being used, value should be set to `consul-api-gateway` * Type: string * Required: required ### listeners Specifies the `listeners` associated with the `Gateway`. At least one `listener` must be specified. Each `listener` within a `Gateway` must have a unique combination of `hostname`, `port`, and `protocol`. - * Type: array of objects * Required: required diff --git a/website/content/docs/api-gateway/configuration/gatewayclass.mdx b/website/content/docs/api-gateway/configuration/gatewayclass.mdx index 2a5104f518..8f25467598 100644 --- a/website/content/docs/api-gateway/configuration/gatewayclass.mdx +++ b/website/content/docs/api-gateway/configuration/gatewayclass.mdx @@ -43,17 +43,23 @@ An object that defines additional configuration required by the gateway controll * Required: required ### parametersRef.group -When using Consul API Gateway, this value should be equal to `api-gateway.consul.hashicorp.com` +The Kubernetes group of the `parametersRef`. This value will always be the same across all deployments of Consul API Gateway. * Type: Group * Required: required +You must specify the following value: +* `api-gateway.consul.hashicorp.com` + ### parametersRef.kind -When using Consul API Gateway, this value should be equal to `GatewayClassConfig` -* Type: object +The Kubernetes kind of the `parametersRef`. This value will always be the same across all deployments of Consul API Gateway. +* Type: Kind * Required: required +You must specify the following value: +* `GatewayClassConfig` + ### parametersRef.name -The name of the `GatewayClass` +The name of the `GatewayClassConfig` object * Type: object * Required: required diff --git a/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx b/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx index 8a321be388..0eef0d15a6 100644 --- a/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx +++ b/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx @@ -93,6 +93,10 @@ Specifies the scheme to use for connecting to Consul. The supported values are ` * Required: optional * Default: `http` +You can specify the following strings: +* `http` +* `https` + ### 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 @@ -133,20 +137,34 @@ Most deployments will use the default value unless a specific version of Envoy i * Default: `"envoyproxy/envoy:RELEASE_VERSION"` ### logLevel -Specifies the error reporting level for logs. You can specify the following values: `error`, `warning`, `info`, `debug`, `trace`. +Specifies the error reporting level for logs. * Type: string * Required: optional * Default: `info` +You can specify the following strings: +* `error` +* `warning` +* `info` +* `debug` +* `trace` + ### 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`. +Specifies the ingress methods for a service. * Type: string * Required: optional +You can specify the following strings: +* `ClusterIP`: Gateway will only be accessible from inside the cluster +* `NodePort`: Gateway will be exposed on each Kubernetes node at a static port +* `LoadBalancer`: Gateway will be 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 diff --git a/website/content/docs/api-gateway/configuration/index.mdx b/website/content/docs/api-gateway/configuration/index.mdx index 8952a0dc4a..32343b079d 100644 --- a/website/content/docs/api-gateway/configuration/index.mdx +++ b/website/content/docs/api-gateway/configuration/index.mdx @@ -14,4 +14,10 @@ This topic provides an overview of the configuration items that enable Consul AP - [GatewayClass](/docs/api-gateway/configuration/gatewayclass): Defines a class of gateway resources that you can use as a template for creating gateways. - [Routes](/docs/api-gateway/configuration/routes): Specifies the path from the gateway to the backend service(s)client to the listener. +A basic Gateway object can simply use the default [`gatewayClassName`](/docs/api-gateway/configuration/gateway###gatewayClassName) `consul-api-gateway`. For additional configruation options follow the following steps. + +1. Define a [GatewayClassConfig](/docs/api-gateway/configuration/gatewayclassconfig) containing your desired configurations. +1. Define a [GatewayClass](/docs/api-gateway/configuration/gatewayclass) with [`parametersRef.name`](/docs/api-gateway/configuration/gatewayclass###parametersRef.name) set to the name of the newly defined [GatewayClassConfig](/docs/api-gateway/configuration/gatewayclassconfig) +1. Define a [Gateway](/docs/api-gateway/configuration/gateway) with [`gatewayClassName`](/docs/api-gateway/configuration/gateway###gatewayClassName) set to the name of the newly defined [GatewayClass](/docs/api-gateway/configuration/gatewayclass) + From e551ac878f4a288bbbbda6011ea9d2942a636944 Mon Sep 17 00:00:00 2001 From: Sarah Alsmiller Date: Tue, 26 Jul 2022 10:25:48 -0500 Subject: [PATCH 052/124] fix links --- .../api-gateway/configuration/gateway.mdx | 42 ++++++++-------- .../configuration/gatewayclass.mdx | 10 ++-- .../configuration/gatewayclassconfig.mdx | 48 +++++++++---------- .../docs/api-gateway/configuration/index.mdx | 8 ++-- .../docs/api-gateway/configuration/routes.mdx | 40 ++++++++-------- 5 files changed, 74 insertions(+), 74 deletions(-) diff --git a/website/content/docs/api-gateway/configuration/gateway.mdx b/website/content/docs/api-gateway/configuration/gateway.mdx index d30123e09c..e1c8400a66 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`)[###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 +* (`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 diff --git a/website/content/docs/api-gateway/configuration/gatewayclass.mdx b/website/content/docs/api-gateway/configuration/gatewayclass.mdx index 8f25467598..0a02c5616e 100644 --- a/website/content/docs/api-gateway/configuration/gatewayclass.mdx +++ b/website/content/docs/api-gateway/configuration/gatewayclass.mdx @@ -21,11 +21,11 @@ The `GatewayClass` resource is a generic kubernetes gateway object. For configur ## 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 +* (`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 diff --git a/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx b/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx index 0eef0d15a6..6bb669472b 100644 --- a/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx +++ b/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx @@ -15,30 +15,30 @@ The `GatewayClassConfig` object contains Consul API Gateway-related configuratio ## 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 +* (`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 diff --git a/website/content/docs/api-gateway/configuration/index.mdx b/website/content/docs/api-gateway/configuration/index.mdx index 32343b079d..9c5606a404 100644 --- a/website/content/docs/api-gateway/configuration/index.mdx +++ b/website/content/docs/api-gateway/configuration/index.mdx @@ -9,15 +9,15 @@ description: >- This topic provides an overview of the configuration items that enable Consul API Gateway to facilitate ingress into your Consul service mesh. -- [Gateway](/docs/api-gateway/configuration/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](/docs/api-gateway/configuration/gateway#listeners)), which specify the logical endpoints bound to the gateway's addresses. Refer to Configuration > Gateway for details on configuration. +- [Gateway](/docs/api-gateway/configuration/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](/docs/api-gateway/configuration/gateway#listeners)), which specify the logical endpoints bound to the gateway's addresses. - [GatewayClassConfig](/docs/api-gateway/configuration/gatewayclassconfig): Describes additional Consul API Gateway-related configuration parameters for the GatewayClass resource. - [GatewayClass](/docs/api-gateway/configuration/gatewayclass): Defines a class of gateway resources that you can use as a template for creating gateways. - [Routes](/docs/api-gateway/configuration/routes): Specifies the path from the gateway to the backend service(s)client to the listener. -A basic Gateway object can simply use the default [`gatewayClassName`](/docs/api-gateway/configuration/gateway###gatewayClassName) `consul-api-gateway`. For additional configruation options follow the following steps. +A basic Gateway object can simply use the default [`gatewayClassName`](/docs/api-gateway/configuration/gateway#gatewayClassName) `consul-api-gateway`. For additional configruation options follow the following steps. 1. Define a [GatewayClassConfig](/docs/api-gateway/configuration/gatewayclassconfig) containing your desired configurations. -1. Define a [GatewayClass](/docs/api-gateway/configuration/gatewayclass) with [`parametersRef.name`](/docs/api-gateway/configuration/gatewayclass###parametersRef.name) set to the name of the newly defined [GatewayClassConfig](/docs/api-gateway/configuration/gatewayclassconfig) -1. Define a [Gateway](/docs/api-gateway/configuration/gateway) with [`gatewayClassName`](/docs/api-gateway/configuration/gateway###gatewayClassName) set to the name of the newly defined [GatewayClass](/docs/api-gateway/configuration/gatewayclass) +1. Define a [GatewayClass](/docs/api-gateway/configuration/gatewayclass) with [`parametersRef.name`](/docs/api-gateway/configuration/gatewayclass#parametersRef-name) set to the name of the newly defined [GatewayClassConfig](/docs/api-gateway/configuration/gatewayclassconfig) +1. Define a [Gateway](/docs/api-gateway/configuration/gateway) with [`gatewayClassName`](/docs/api-gateway/configuration/gateway#gatewayClassName) set to the name of the newly defined [GatewayClass](/docs/api-gateway/configuration/gatewayclass) diff --git a/website/content/docs/api-gateway/configuration/routes.mdx b/website/content/docs/api-gateway/configuration/routes.mdx index 13e720f56e..7819d482f6 100644 --- a/website/content/docs/api-gateway/configuration/routes.mdx +++ b/website/content/docs/api-gateway/configuration/routes.mdx @@ -47,33 +47,33 @@ The following example creates a route named `example-route` in namespace `gatewa apiVersion: gateway.networking.k8s.io/v1alpha2 kind: HTTPRoute metadata: - name: example-route - namespace: gateway-namespace + name: example-route + namespace: gateway-namespace spec: - parentRefs: - - name: example-gateway - rules: - - backendRefs: - - kind: Service - name: echo - namespace: service-namespace - port: 8080 + parentRefs: + - name: example-gateway + rules: + - backendRefs: + - kind: Service + name: echo + namespace: service-namespace + port: 8080 --- apiVersion: gateway.networking.k8s.io/v1alpha2 kind: ReferencePolicy metadata: - name: reference-policy - namespace: service-namespace + name: reference-policy + namespace: service-namespace spec: - from: - - group: gateway.networking.k8s.io - kind: HTTPRoute - namespace: gateway-namespace - to: - - group: "" - kind: Service - name: echo + from: + - group: gateway.networking.k8s.io + kind: HTTPRoute + namespace: gateway-namespace + to: + - group: "" + kind: Service + name: echo ``` From b2cf7f0d3defdeaf12f4c2cd374618a7fade2638 Mon Sep 17 00:00:00 2001 From: Sarah Alsmiller Date: Tue, 26 Jul 2022 12:34:10 -0500 Subject: [PATCH 053/124] fix links --- .../api-gateway/configuration/gateway.mdx | 42 ++++++++-------- .../configuration/gatewayclass.mdx | 12 ++--- .../configuration/gatewayclassconfig.mdx | 50 +++++++++---------- .../docs/api-gateway/configuration/index.mdx | 6 +-- 4 files changed, 55 insertions(+), 55 deletions(-) diff --git a/website/content/docs/api-gateway/configuration/gateway.mdx b/website/content/docs/api-gateway/configuration/gateway.mdx index e1c8400a66..135d22f9f2 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`)[#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 +* [`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 diff --git a/website/content/docs/api-gateway/configuration/gatewayclass.mdx b/website/content/docs/api-gateway/configuration/gatewayclass.mdx index 0a02c5616e..0c57ad6c04 100644 --- a/website/content/docs/api-gateway/configuration/gatewayclass.mdx +++ b/website/content/docs/api-gateway/configuration/gatewayclass.mdx @@ -21,12 +21,12 @@ The `GatewayClass` resource is a generic kubernetes gateway object. For configur ## 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 +* [`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 diff --git a/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx b/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx index 6bb669472b..e0061e346f 100644 --- a/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx +++ b/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx @@ -15,30 +15,30 @@ The `GatewayClassConfig` object contains Consul API Gateway-related configuratio ## 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 +* [`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 @@ -98,7 +98,7 @@ You can specify the following strings: * `https` ### copyAnnotations.service -List of kubernetes (annotations)[https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/] to copy to the gateway 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 diff --git a/website/content/docs/api-gateway/configuration/index.mdx b/website/content/docs/api-gateway/configuration/index.mdx index 9c5606a404..fd1ac2a9dd 100644 --- a/website/content/docs/api-gateway/configuration/index.mdx +++ b/website/content/docs/api-gateway/configuration/index.mdx @@ -14,10 +14,10 @@ This topic provides an overview of the configuration items that enable Consul AP - [GatewayClass](/docs/api-gateway/configuration/gatewayclass): Defines a class of gateway resources that you can use as a template for creating gateways. - [Routes](/docs/api-gateway/configuration/routes): Specifies the path from the gateway to the backend service(s)client to the listener. -A basic Gateway object can simply use the default [`gatewayClassName`](/docs/api-gateway/configuration/gateway#gatewayClassName) `consul-api-gateway`. For additional configruation options follow the following steps. +A basic Gateway object can simply use the default [`gatewayClassName`](/docs/api-gateway/configuration/gateway#gatewayclassname) `consul-api-gateway`. For additional configruation options follow the following steps. 1. Define a [GatewayClassConfig](/docs/api-gateway/configuration/gatewayclassconfig) containing your desired configurations. -1. Define a [GatewayClass](/docs/api-gateway/configuration/gatewayclass) with [`parametersRef.name`](/docs/api-gateway/configuration/gatewayclass#parametersRef-name) set to the name of the newly defined [GatewayClassConfig](/docs/api-gateway/configuration/gatewayclassconfig) -1. Define a [Gateway](/docs/api-gateway/configuration/gateway) with [`gatewayClassName`](/docs/api-gateway/configuration/gateway#gatewayClassName) set to the name of the newly defined [GatewayClass](/docs/api-gateway/configuration/gatewayclass) +1. Define a [GatewayClass](/docs/api-gateway/configuration/gatewayclass) with [`parametersRef.name`](/docs/api-gateway/configuration/gatewayclass#parametersref-name) set to the name of the newly defined [GatewayClassConfig](/docs/api-gateway/configuration/gatewayclassconfig) +1. Define a [Gateway](/docs/api-gateway/configuration/gateway) with [`gatewayClassName`](/docs/api-gateway/configuration/gateway#gatewayclassname) set to the name of the newly defined [GatewayClass](/docs/api-gateway/configuration/gatewayclass) From 43e4f09a1633306a25b210091b43291e75c88712 Mon Sep 17 00:00:00 2001 From: Sarah Alsmiller Date: Tue, 26 Jul 2022 12:42:46 -0500 Subject: [PATCH 054/124] update controllername to match previous style --- .../content/docs/api-gateway/configuration/gatewayclass.mdx | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/configuration/gatewayclass.mdx b/website/content/docs/api-gateway/configuration/gatewayclass.mdx index 0c57ad6c04..918b872523 100644 --- a/website/content/docs/api-gateway/configuration/gatewayclass.mdx +++ b/website/content/docs/api-gateway/configuration/gatewayclass.mdx @@ -33,10 +33,13 @@ The `GatewayClass` resource is a generic kubernetes gateway object. For configur 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'` +The name of the controller that is managing the gateways of this class. * Type: string * Required: required +You must specify the following value: +* `'hashicorp.com/consul-api-gateway-controller'` + ### parametersRef An object that defines additional configuration required by the gateway controller. * Type: object From 243519c8efe1382cda5b4851570ee38fa895b940 Mon Sep 17 00:00:00 2001 From: Sarah Alsmiller Date: Tue, 26 Jul 2022 12:59:28 -0500 Subject: [PATCH 055/124] fix links --- website/content/docs/api-gateway/configuration/gateway.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/configuration/gateway.mdx b/website/content/docs/api-gateway/configuration/gateway.mdx index 135d22f9f2..ea01afa627 100644 --- a/website/content/docs/api-gateway/configuration/gateway.mdx +++ b/website/content/docs/api-gateway/configuration/gateway.mdx @@ -43,7 +43,7 @@ Specify the following parameters to declare a Gateway: * [`hostname`](#listeners-hostname): string | required * [`name`](#listeners-name): string | required * [`port`](#listeners-port): integer | required - * [`protocol`](#listeners-protocol]`: string | 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 From 5dad74df3c80ad262683a91e957c779e1c3ea5f6 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Wed, 27 Jul 2022 15:27:04 -0700 Subject: [PATCH 056/124] fixed links and clarified some sections in gateway configuration doc --- .../api-gateway/configuration/gateway.mdx | 123 ++++++++++-------- 1 file changed, 66 insertions(+), 57 deletions(-) diff --git a/website/content/docs/api-gateway/configuration/gateway.mdx b/website/content/docs/api-gateway/configuration/gateway.mdx index ea01afa627..61b36b65eb 100644 --- a/website/content/docs/api-gateway/configuration/gateway.mdx +++ b/website/content/docs/api-gateway/configuration/gateway.mdx @@ -2,7 +2,7 @@ layout: docs page_title: Consul API Gateway Gateway description: >- - Consul API Gateway Gateway + This topic descrbes how to configure the Consul API Gateway Gateway object --- # Gateway @@ -22,34 +22,36 @@ Specify the following parameters to declare a Gateway: | `kind` | Specifies the type of configuration object. The value should always be `Gateway`. | Required | | `description` | Human-readable string that describes the purpose of the `Gateway`. | Optional | | `version ` | Specifies the Kubernetes API version. The value should always be `gateway.networking.k8s.io/v1alpha2` | Required | -| `scope` | Specifies the effective scope of the Gateway. The value should always be namespaced. | Required | -| `fields` | Specifies the configurations for the Gateway. The fields are listed in the Configuration model. Details for each field are described in the Specification. | Required | +| `scope` | Specifies the effective scope of the Gateway. The value should always be `namespaced`. | Required | +| `fields` | Specifies the configurations for the Gateway. The fields are listed in the [configuration model](#configuration-model). Details for each field are described in the [specification](#specification). | Required | ## Configuration model -* [`gatewayClassName`](#gatewayClassName): string | required +The following outline shows how to format the configurations in the `Gateway` object. Click on a property name to view details about the configuration. + +* [`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 + * [`allowedRoutes`](#listeners-allowedroutes): object | required + * [`namespaces`](#listeners-allowedroutes-namespaces): object | required + * [`from`](#listeners-namespaces-from): string | required + * [`selector`](#listeners-allowedroutes-namespaces-selector): object | required if `from` is configured to `selector` + * [`matchExpressions`](#listeners-allowedroutes-namespaces-selector-matchexpressions): array of objects | required if `matchLabels` is not configured + * [`key`](#listeners-allowedroutes-namespaces-selector-matchexpressions): string | required if `matchExpressions` is declared + * [`operator`](#listeners-allowedroutes-namespaces-selector-matchexpressions): string | required if `matchExpressions` is declared + * [`values`](#listeners-allowedroutes-namespaces-selector-matchexpressions): array of strings | required if `matchExpressions` is declared + * [`matchLabels`](#listeners-allowedroutes-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 + * [`tls`](#listeners-tls): object | required if `protocol` is set to `HTTPS` + * [`certificateRefs`](#listeners-tls): array or objects | required if `tls` is declared + * [`name`](#listeners-tls): string | required if `certificateRefs` is declared + * [`namespace`](#listeners-tls): string | required if `certificateRefs` is declared + * [`mode`](#listeners-tls): string | required if `certificateRefs` is declared + * [`options`](#listeners-tls): map of strings | optional ## Specification @@ -74,37 +76,34 @@ Specifies a `namespace` object that defines the types of routes that may be atta Determines which routes are allowed to attach to the `listener`. Only routes in the same namespace as the `Gateway` may be attached by default. ### listeners.allowedRoutes.namespaces.from -Specifies the policy for which namespaces a route may attach to a `Gateway` from. Defaults to `Same`. +Determines which namespaces are allowed to attach a route to the `Gateway`. You can specify one of the following strings: -This parameter has the following properties: -* Type: string -* Required: required - -You can specify one of the following strings: * `All`: Routes in all namespaces may be attached to the `Gateway`. -* `Same`: Only routes in the same namespace as the `Gateway` may be attached. -* `Selector`: Only routes in namespaces that match the `selector` may be attached. +* `Same` (default): Only routes in the same namespace as the `Gateway` may be attached. +* `Selector`: Only routes in namespaces that match the [`selector`](#listeners-allowedroutes-namespaces-selector) may be attached. + +This parameter is required. ### listeners.allowedRoutes.namespaces.selector -Specifies a method of matching namespaces from which routes are allowed to attach to the listener. -* Type: Object -* Required: Required when `from` is configured to `Selector`. +Specifies a method for selecting routes that are allowed to attach to the listener. The `Gateway` checks for namespaces in the network that match either a regular expression or a label. Routes from the matching namespace are allowed to attach to the listener. -The selector configuration contains one of the following objects: -* `matchExpressions` -* `matchLabels` +You can configure one of the following objects: + +* [`matchExpressions`](#listeners-allowedroutes-namespaces-selector-matchexpressions) +* [`matchLabels`](#listeners-allowedroutes-namespaces-selector-matchlabels) + +This field is required when [`from`](#listeners-allowedroutes-namespaces-from) is configured to `Selector`. ### listeners.allowedRoutes.namespaces.selector.matchExpressions 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 | -|`scope` | Specifies the effective scope of the Gateway. The value should always be namespaced. | Required | -|`fields` | Specifies the configurations for the Gateway. The fields are listed in the Configuration model. Details for each field are described in the Specification. | Required | +| Requirement | Description | Type | Required | +|--- |--- |--- |--- | +|`key` | Specifies the label that the `key` applies to. | string | required when `matchExpressions` is declared | +|`operator` | Specifies the key's relation to a set of values. You can use the following keywords:
  • `In`: Only routes in namespaces that contain the strings in the `values` field can attach to the `Gateway`.
  • `NotIn`: Routes in namespaces that do not contain the strings in the `values` field can attach to the `Gateway`.
  • `Exists`: Routes in namespaces that contain the `key` value are allowed to attach to the `Gateway`.
  • `DoesNotExist`: Routes in namespaces that do not contain the `key` value are allowed to attach to the `Gateway`.
| string | required when `matchExpressions` is declared | +|`values` | Specifies an array of string values. If `operator` is configured to `In` or `NotIn`, then the `values` array must contain values. If `operator` is configured to `Exists` or `DoesNotExist`, then the `values` array must be empty. This array is replaced during a strategic merge patch. | array of strings | required when `matchExpressions` is declared | +In the following example, routes in namespaces that contain `foo` and `bar` are allowed to attach routes to the `Gateway`. ```yaml namespaceSelector: matchExpressions: @@ -118,52 +117,62 @@ namespaceSelector: ### listeners.allowedRoutes.namespaces.selector.matchLabels Specifies an array of labels and label values. If a match is found, then routes with the matching label(s) are allowed to attach to the `Gateway`. This selector can contain any arbitrary key/value pair. +In the following example, routes in namespaces that have a `bar` label are allowed to attache to the `Gateway`. ```yaml namespaceSelector: matchLabels: foo: bar ``` -For more on labels, see [Labels and Selectors](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) +Refer to [Labels and Selectors](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) in the Kubernetes documentation for additional information about labels. ### listeners.hostname -Specifies the `listener`'s hostname +Specifies the `listener`'s hostname. * Type: string * Required: required ### listeners.name -Specifies the `listener`'s name +Specifies the `listener`'s name. * Type: string * Required: required ### listeners.port -Specifies the port number that the `listener` will attach to +Specifies the port number that the `listener` attaches to. * Type: integer * Required: required ### listeners.protocol -Specifies the protocol the `listener` will use +Specifies the protocol the `listener` communicates on. * Type: string * Required: required Allowed values are `TCP`, `HTTP`, or `HTTPS` ### listeners.tls -* Type: Object -* Required: required if `protocol` is set to `HTTPS` +Specifies the `tls` configurations for the `Gateway`. The `tls` object is required if `protocol` is set to `HTTPS`. The object contains the following fields: -### listeners.tls.certificateRefs -`CertificateRefs` contains a series of references to Kubernetes objects that contains TLS certificates and private keys. These certificates are used to establish a TLS handshake for requests that match the hostname of the associated `listener`. Each reference must be a Kubernetes Secret, and, if using a Secret in a namespace other than the`Gateway`'s, must have a corresponding `ReferencePolicy` created. -* Type: Object or Array -* Required: required if `tls` is set +| Parameter | Description | Type | Required | +| --- | --- | --- | --- | +| `certificateRefs` |
Specifies Kubernetes `name` and `namespace` objects that contains TLS certificates and private keys.
The certificates establish a TLS handshake for requests that match the `hostname` of the associated `listener`. Each reference must be a Kubernetes Secret. If you are using a Secret in a namespace other than the `Gateway`'s, each reference must also have a corresponding [`ReferencePolicy`](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.ReferencePolicy).
| Object or array | Required if `tls` is set | +| `mode` | Specifies the ? | string | Required if `certificateRefs` is set | +| `options` | ??? | Map of strings | optional | -### listeners.tls.mode -* Type: String -* Required: required if certificateRefs is set +In the following example, `tls` settings are configured . . . + +```yaml + +tls: + certificateRefs: + name: ? + namespace: ? + mode: ? + options: + - ? + - ? + - ? + +``` -### listeners.tls.options -* Type: Map of Strings -* Required: optional ## Complete configuration The following example shows a fully configured `Gateway`. From 62003637df2975c6d15d37e1b18049bc231c5fd2 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Wed, 27 Jul 2022 15:32:26 -0700 Subject: [PATCH 057/124] fixed small typo --- website/content/docs/api-gateway/configuration/gateway.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/configuration/gateway.mdx b/website/content/docs/api-gateway/configuration/gateway.mdx index 61b36b65eb..8907b753e1 100644 --- a/website/content/docs/api-gateway/configuration/gateway.mdx +++ b/website/content/docs/api-gateway/configuration/gateway.mdx @@ -117,7 +117,8 @@ namespaceSelector: ### listeners.allowedRoutes.namespaces.selector.matchLabels Specifies an array of labels and label values. If a match is found, then routes with the matching label(s) are allowed to attach to the `Gateway`. This selector can contain any arbitrary key/value pair. -In the following example, routes in namespaces that have a `bar` label are allowed to attache to the `Gateway`. +In the following example, routes in namespaces that have a `bar` label are allowed to attach to the `Gateway`. + ```yaml namespaceSelector: matchLabels: From 176a56839ead54867e52d90a7740511417b9ae56 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Wed, 27 Jul 2022 16:08:54 -0700 Subject: [PATCH 058/124] minor changes to the gatewayclass documentation --- .../configuration/gatewayclass.mdx | 41 +++++++++---------- 1 file changed, 20 insertions(+), 21 deletions(-) diff --git a/website/content/docs/api-gateway/configuration/gatewayclass.mdx b/website/content/docs/api-gateway/configuration/gatewayclass.mdx index 918b872523..f231fed999 100644 --- a/website/content/docs/api-gateway/configuration/gatewayclass.mdx +++ b/website/content/docs/api-gateway/configuration/gatewayclass.mdx @@ -17,15 +17,16 @@ The value of the `controllerName` field must be set to `hashicorp.com/consul-api When gateways are created from a `GatewayClass`, they use the parameters specified in the `GatewayClass` at the time of instantiation. -The `GatewayClass` resource is a generic kubernetes gateway object. For configuration specific to Consul API Gateway, see [GatewayClassConfig](/docs/api-gateway/configuration/gatewayclassconfig). +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 +The following outline shows how to format the configurations in the `GatewayClass` object. Click on a property name to view details about the configuration. * [`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 + * [`group`]([#parametersref-group): string | required is `parametersRef` is set + * [`kind`](#parametersref-kind): string | required is `parametersRef` is set + * [`name`](#parametersref-name): string | required is `parametersRef` is set * [`description`](#description): string | optional ## Specification @@ -33,41 +34,39 @@ The `GatewayClass` resource is a generic kubernetes gateway object. For configur This topic provides details about the configuration parameters. ### controllerName -The name of the controller that is managing the gateways of this class. +Specifies the name of the controller that manages the gateways generated by this class. The value must alwasy be `'hashicorp.com/consul-api-gateway-controller'`. + * Type: string * Required: required -You must specify the following value: -* `'hashicorp.com/consul-api-gateway-controller'` - ### parametersRef -An object that defines additional configuration required by the gateway controller. +Defines an object that specifies additional configurations required by the gateway controller. * Type: object * Required: required ### parametersRef.group -The Kubernetes group of the `parametersRef`. This value will always be the same across all deployments of Consul API Gateway. -* Type: Group -* Required: required +Specifies the Kubernetes group that the `parametersRef` is a member of. The value must always be `api-gateway.consul.hashicorp.com`. -You must specify the following value: -* `api-gateway.consul.hashicorp.com` +The `parametersRef.group` is always the same across all deployments of Consul API Gateway. + +* Type: string +* Required: required ### parametersRef.kind -The Kubernetes kind of the `parametersRef`. This value will always be the same across all deployments of Consul API Gateway. -* Type: Kind +Specifies the Kubernetes kind of entity that the `parametersRef` is. The value must always be `GatewayClassConfig`. + +This `parametersRef.kind` is always the same across all deployments of Consul API Gateway. + +* Type: string * Required: required -You must specify the following value: -* `GatewayClassConfig` - ### parametersRef.name -The name of the `GatewayClassConfig` object +Specfies the name of the `GatewayClassConfig` object. * Type: object * Required: required ### description -Helps describe a gateway class with more details +Specifies a human-readable description of the gateway class. We recommend including a description so that a record exists that describes the gateway class's purpose. * Type: string * Required: optional From 6b932b50991dd6169fd3157fbeeaf183440d1651 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Thu, 28 Jul 2022 10:02:12 -0700 Subject: [PATCH 059/124] more tweaks to gatewayclass docs --- .../configuration/gatewayclass.mdx | 50 +++++++------------ 1 file changed, 17 insertions(+), 33 deletions(-) diff --git a/website/content/docs/api-gateway/configuration/gatewayclass.mdx b/website/content/docs/api-gateway/configuration/gatewayclass.mdx index f231fed999..7690c452c9 100644 --- a/website/content/docs/api-gateway/configuration/gatewayclass.mdx +++ b/website/content/docs/api-gateway/configuration/gatewayclass.mdx @@ -7,13 +7,11 @@ description: >- # GatewayClass -This topic provides full details about the `GatewayClass` resource +This topic provides describes how to configure the `GatewayClass` resource, which is a generic Kubernetes gateway object used as a template for creating `Gateway` resources. ## 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`. +The `GatewayClass` 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. @@ -23,10 +21,10 @@ The `GatewayClass` resource is a generic Kubernetes gateway object. For configur The following outline shows how to format the configurations in the `GatewayClass` object. Click on a property name to view details about the configuration. * [`controllerName`](#controllername): string | required -* [`parametersRef`](#parametersref): object | optional - * [`group`]([#parametersref-group): string | required is `parametersRef` is set - * [`kind`](#parametersref-kind): string | required is `parametersRef` is set - * [`name`](#parametersref-name): string | required is `parametersRef` is set +* [`parametersRef`](#parametersref): object | required + * [`group`](#parametersref): string | required if `parametersRef` is set + * [`kind`](#parametersref): string | required if `parametersRef` is set + * [`name`](#parametersref): string | required if `parametersRef` is set * [`description`](#description): string | optional ## Specification @@ -34,39 +32,24 @@ The following outline shows how to format the configurations in the `GatewayClas This topic provides details about the configuration parameters. ### controllerName -Specifies the name of the controller that manages the gateways generated by this class. The value must alwasy be `'hashicorp.com/consul-api-gateway-controller'`. +Specifies the name of the controller that manages the gateways generated by this class. +The value must always be `hashicorp.com/consul-api-gateway-controller`. * Type: string * Required: required ### parametersRef -Defines an object that specifies additional configurations required by the gateway controller. -* Type: object -* Required: required +Defines an API object that references additional configurations required by the gateway controller. The following table describes the fields that you must include in the `parametersRef` coniguration. -### parametersRef.group -Specifies the Kubernetes group that the `parametersRef` is a member of. The value must always be `api-gateway.consul.hashicorp.com`. - -The `parametersRef.group` is always the same across all deployments of Consul API Gateway. - -* Type: string -* Required: required - -### parametersRef.kind -Specifies the Kubernetes kind of entity that the `parametersRef` is. The value must always be `GatewayClassConfig`. - -This `parametersRef.kind` is always the same across all deployments of Consul API Gateway. - -* Type: string -* Required: required - -### parametersRef.name -Specfies the name of the `GatewayClassConfig` object. -* Type: object -* Required: required +| Parameter | Description | Type | Required | +| --- | --- | --- | --- | +| `group` | Specifies the Kubernetes group that the `parametersRef` is a member of.
The value must always be `api-gateway.consul.hashicorp.com`.
The `parametersRef.group` is always the same across all deployments of Consul API Gateway. | String | Required | +| `kind` | Specifies the type of Kubernetes object that the `parametersRef` configuration defines.
The value must always be `GatewayClassConfig`.
This `parametersRef.kind` is always the same across all deployments of Consul API Gateway. | String | Required | +| `name` | Specfies a name for the `GatewayClassConfig` object. | String | Required | ### description -Specifies a human-readable description of the gateway class. We recommend including a description so that a record exists that describes the gateway class's purpose. +Specifies a human-readable description of the gateway class. We recommend using the description field to describe the gateway class's purpose. + * Type: string * Required: optional @@ -86,6 +69,7 @@ The following example creates a gateway class called `test-gateway-class`: group: api-gateway.consul.hashicorp.com kind: GatewayClassConfig name: test-gateway-class-config + description: The gateway class is for creating test gateways class configurations ``` From 692767d88d8af71f961306f25f70ef0fdfaedc6f Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Thu, 28 Jul 2022 11:04:21 -0700 Subject: [PATCH 060/124] tweaks to the configuration overview page --- website/content/docs/api-gateway/configuration/index.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/website/content/docs/api-gateway/configuration/index.mdx b/website/content/docs/api-gateway/configuration/index.mdx index fd1ac2a9dd..59e95e18a7 100644 --- a/website/content/docs/api-gateway/configuration/index.mdx +++ b/website/content/docs/api-gateway/configuration/index.mdx @@ -14,10 +14,10 @@ This topic provides an overview of the configuration items that enable Consul AP - [GatewayClass](/docs/api-gateway/configuration/gatewayclass): Defines a class of gateway resources that you can use as a template for creating gateways. - [Routes](/docs/api-gateway/configuration/routes): Specifies the path from the gateway to the backend service(s)client to the listener. -A basic Gateway object can simply use the default [`gatewayClassName`](/docs/api-gateway/configuration/gateway#gatewayclassname) `consul-api-gateway`. For additional configruation options follow the following steps. +You can implement the default [`gatewayClassName`](/docs/api-gateway/configuration/gateway#gatewayclassname) (`consul-api-gateway`) to create a basic Gateway object. You can also complete the following steps to create custom Gateways suitable for your environment: -1. Define a [GatewayClassConfig](/docs/api-gateway/configuration/gatewayclassconfig) containing your desired configurations. -1. Define a [GatewayClass](/docs/api-gateway/configuration/gatewayclass) with [`parametersRef.name`](/docs/api-gateway/configuration/gatewayclass#parametersref-name) set to the name of the newly defined [GatewayClassConfig](/docs/api-gateway/configuration/gatewayclassconfig) -1. Define a [Gateway](/docs/api-gateway/configuration/gateway) with [`gatewayClassName`](/docs/api-gateway/configuration/gateway#gatewayclassname) set to the name of the newly defined [GatewayClass](/docs/api-gateway/configuration/gatewayclass) +1. Define a [GatewayClassConfig](/docs/api-gateway/configuration/gatewayclassconfig) that contains your custom configurations. +1. Define a [GatewayClass](/docs/api-gateway/configuration/gatewayclass) and configure the [`parametersRef.name`](/docs/api-gateway/configuration/gatewayclass#parametersref-name) to reference the name of your [GatewayClassConfig](/docs/api-gateway/configuration/gatewayclassconfig). +1. Define a [Gateway](/docs/api-gateway/configuration/gateway) and configure the [`gatewayClassName`](/docs/api-gateway/configuration/gateway#gatewayclassname) to reference the name of your [GatewayClass](/docs/api-gateway/configuration/gatewayclass). From 7e2cece37634b94e0df926ad96a4625545b8f3fb Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Thu, 28 Jul 2022 11:38:50 -0700 Subject: [PATCH 061/124] tweaks to the basic usage topic --- website/content/docs/api-gateway/usage/basic-usage.mdx | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/website/content/docs/api-gateway/usage/basic-usage.mdx b/website/content/docs/api-gateway/usage/basic-usage.mdx index d5cd194776..d06cdb2bd6 100644 --- a/website/content/docs/api-gateway/usage/basic-usage.mdx +++ b/website/content/docs/api-gateway/usage/basic-usage.mdx @@ -8,6 +8,8 @@ description: >- # Basic Usage +This topic describes the basic workflow for implementing Consul API Gateway configurations. + 1. Verify that the [requirements](/docs/api-gateway/consul-api-gateway-install#requirments) have been met. 1. Verify that the Consul API Gateway CRDs and controller have been installed and applied (see [Installation](/docs/api-gateway/consul-api-gateway-install)). 1. Configure the artifacts as describe in the [Configuration](/docs/api-gateway/configuration) section. @@ -79,7 +81,11 @@ consul-api-gateway 0.1.0 ## Error Messages -If the error message is not listed on this page, it may be listed on the main [Consul Common errors][consul-common-errors] page. If the error message is not listed on that page either, please consider following our general [Troubleshooting Guide][troubleshooting] or reach out to us in [Discuss](https://discuss.hashicorp.com/). +This topic provides information about potential error messages associated with Consul API Gateway. If your receive an error message that does not appear in this section, refer to the following resources: + +* [Common Consul errors](/docs/troubleshoot/common-errors#common-errors-on-kubernetes) +* [Consul troubleshooting guide](/docs/troubleshoot/common-errors) +* [Consul Discuss forum](https://discuss.hashicorp.com/)