diff --git a/changelogs/unreleased/4122-skriss-docs.md b/changelogs/unreleased/4122-skriss-docs.md new file mode 100644 index 00000000000..1543eaeab72 --- /dev/null +++ b/changelogs/unreleased/4122-skriss-docs.md @@ -0,0 +1 @@ +Adds a Gateway API v1alpha2 guide. diff --git a/site/content/guides/gateway-api-v1alpha2.md b/site/content/guides/gateway-api-v1alpha2.md new file mode 100644 index 00000000000..2d25e146b51 --- /dev/null +++ b/site/content/guides/gateway-api-v1alpha2.md @@ -0,0 +1,150 @@ +--- +title: Using Gateway API v1alpha2 with Contour +layout: page +--- + +## Introduction + +[Gateway API][1] is an open source project managed by the Kubernetes SIG-NETWORK community. The project's goal is to +evolve service networking APIs within the Kubernetes ecosystem. Gateway API consists of multiple resources that provide +user interfaces to expose Kubernetes applications- Services, Ingress, and more. + +This guide covers using version **v1alpha2** of the Gateway API, with Contour `v1.20.0-beta.1`. +Please note that this is pre-release software, and we don't recommend installing it in a production environment. + +### Background + +Gateway API targets three personas: + +- __Platform Provider__: The Platform Provider is responsible for the overall environment that the cluster runs in, i.e. + the cloud provider. The Platform Provider will interact with GatewayClass and Contour resources. +- __Platform Operator__: The Platform Operator is responsible for overall cluster administration. They manage policies, + network access, application permissions and will interact with the Gateway resource. +- __Service Operator__: The Service Operator is responsible for defining application configuration and service + composition. They will interact with xRoute resources and other typical Kubernetes resources. + +Gateway API contains three primary resources: + +- __GatewayClass__: Defines a set of gateways with a common configuration and behavior. +- __Gateway__: Requests a point where traffic can be translated to a Service within the cluster. +- __xRoutes__: Describes how traffic coming via the Gateway maps to the Services. + +Resources are meant to align with personas. For example, a platform operator will create a Gateway, so a developer can +expose an HTTP application using an HTTPRoute resource. + +### Prerequisites +The following prerequisites must be met before using Gateway API with Contour: + +- A working [Kubernetes][2] cluster. Refer to the [compatibility matrix][3] for cluster version requirements. +- The [kubectl][4] command-line tool, installed and configured to access your cluster. + +## Deploying Contour with Gateway API + +### Option #1: Gateway API with Contour + +Refer to the [contour][6] design for additional background on the Gateway API implementation. + +Deploy Contour: +```shell +$ kubectl apply -f https://raw.githubusercontent.com/projectcontour/contour/v1.20.0-beta.1/examples/render/contour-gateway.yaml +``` +This command creates: + +- Namespace `projectcontour` to run Contour. +- Contour CRDs +- Gateway API CRDs +- Contour RBAC resources +- Contour Deployment / Service +- Envoy Daemonset / Service +- Contour ConfigMap enabling Gateway API support +- Gateway API GatewayClass and Gateway + +See the last section ([Testing the Gateway API](#testing-the-gateway-api)) on how to test it all out! + +### Option #2: Using Gateway API with Contour Operator + +Refer to the [contour][6] and [operator][7] designs for additional background on the gateway API implementation. + +Run the operator: +```shell +$ kubectl apply -f https://raw.githubusercontent.com/projectcontour/contour-operator/v1.20.0-beta.1/examples/operator/operator.yaml +``` +This command creates: + +- Namespace `contour-operator` to run the operator. +- Operator and Contour CRDs. +- Operator RBAC resources for the operator. +- A Deployment to manage the operator. +- A Service to front-end the operator’s metrics endpoint. + +Create the Gateway API resources: + +Option 1: Using a LoadBalancer Service: +```shell +$ kubectl apply -f https://raw.githubusercontent.com/projectcontour/contour-operator/v1.20.0-beta.1/examples/gateway/gateway.yaml +``` + +Option 2: Using a NodePort Service: +```shell +$ kubectl apply -f https://raw.githubusercontent.com/projectcontour/contour-operator/v1.20.0-beta.1/examples/gateway/gateway-nodeport.yaml +``` + +Either of the above options create: + +- Namespace `projectcontour` to run the Gateway and child resources, i.e. Envoy DaemonSet. +- A Contour custom resource named `contour-gateway-sample` in the operator's namespace. This resource exposes infrastructure-specific configuration and is referenced by the GatewayClass. +- A GatewayClass named `sample-gatewayclass` that abstracts the infrastructure-specific configuration from Gateways. +- A Gateway named `contour` in namespace `projectcontour`. This gateway will serve the test application through routing rules deployed in the next step. + +See the next section ([Testing the Gateway API](#testing-the-gateway-api)) on how to test it all out! + +## Testing the Gateway API + +Run the test application: +```shell +$ kubectl apply -f https://raw.githubusercontent.com/projectcontour/contour/v1.20.0-beta.1/examples/gateway/kuard/kuard.yaml +``` +This command creates: + +- A Deployment named `kuard` in namespace `projectcontour` to run kuard as the test application. +- A Service named `kuard` in namespace `projectcontour` to expose the kuard application on TCP port 80. +- An HTTPRoute named `kuard` in namespace `projectcontour` to route requests for `local.projectcontour.io` to the kuard + service. + +Verify the kuard resources are available: +```shell +$ kubectl get po,svc,httproute -n projectcontour -l app=kuard +NAME READY STATUS RESTARTS AGE +pod/kuard-798585497b-78x6x 1/1 Running 0 21s +pod/kuard-798585497b-7gktg 1/1 Running 0 21s +pod/kuard-798585497b-zw42m 1/1 Running 0 21s + +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +service/kuard ClusterIP 172.30.168.168 80/TCP 21s + +NAME HOSTNAMES +httproute.gateway.networking.k8s.io/kuard ["local.projectcontour.io"] +``` + +Test access to the kuard application: + +Get the Envoy Service IP address: +```shell +export GATEWAY=$(kubectl -n projectcontour get svc/envoy -o jsonpath='{.status.loadBalancer.ingress[0].hostname}') +``` +__Note:__ Replace `hostname` with `ip` in the above command if your cloud provide uses an IP address for a +load-balancer. + +Use `curl` to test access to the application: +```shell +$ curl -H "Host: local.projectcontour.io" -s -o /dev/null -w "%{http_code}" "http://$GATEWAY/" +``` +A 200 HTTP status code should be returned. + +[1]: https://gateway-api.sigs.k8s.io/ +[2]: https://kubernetes.io/ +[3]: https://projectcontour.io/resources/compatibility-matrix/ +[4]: https://kubernetes.io/docs/tasks/tools/install-kubectl/ +[5]: https://github.com/projectcontour/contour-operator +[6]: https://github.com/projectcontour/contour/blob/main/design/gateway-apis-implementation.md +[7]: https://github.com/projectcontour/contour-operator/blob/main/design/gateway-api.md diff --git a/site/content/guides/gateway-api.md b/site/content/guides/gateway-api.md index f09d9a9dbd9..52767dcfc6a 100644 --- a/site/content/guides/gateway-api.md +++ b/site/content/guides/gateway-api.md @@ -1,5 +1,5 @@ --- -title: Using Gateway API with Contour +title: Using Gateway API v1alpha1 with Contour layout: page --- @@ -9,6 +9,8 @@ layout: page evolve service networking APIs within the Kubernetes ecosystem. Gateway API consists of multiple resources that provide user interfaces to expose Kubernetes applications- Services, Ingress, and more. +This guide covers using version **v1alpha1** of the Gateway API. + ### Background Gateway API targets three personas: