diff --git a/website/docs/tutorials/envoy-gateway/index.md b/website/docs/tutorials/envoy-gateway/index.md new file mode 100644 index 00000000..7a38f43b --- /dev/null +++ b/website/docs/tutorials/envoy-gateway/index.md @@ -0,0 +1,311 @@ +# Envoy Gateway + +[Envoy Gateway](https://gateway.envoyproxy.io/) is an open source project for managing [Envoy Proxy](https://www.envoyproxy.io/) as a standalone or Kubernetes-based application +gateway. [Gateway API](https://gateway-api.sigs.k8s.io/) resources are used to dynamically provision and configure the managed Envoy Proxies. + +This tutorial shows how Envoy Gateway can be configured to delegate authorization decisions to the Kyverno Authz Server. + +## Setup + +### Prerequisites + +- A Kubernetes cluster +- [Helm](https://helm.sh/) to install Envoy Gateway the Kyverno Authz Server +- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) to interact with the cluster + +### Setup a cluster (optional) + +If you don't have a cluster at hand, you can create a local one with [kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation). + +```bash +KIND_IMAGE=kindest/node:v1.31.1 + +# create cluster +kind create cluster --image $KIND_IMAGE --wait 1m +``` + +### Install Envoy Gateway + +First we need to install Envoy Gateway in the cluster. + +```bash +# install envoy gateway +helm install envoy-gateway -n envoy-gateway-system --create-namespace --wait --version v1.2.2 oci://docker.io/envoyproxy/gateway-helm +``` + +### Deploy a sample application + +Httpbin is a well-known application that can be used to test HTTP requests and helps to show quickly how we can play with the request and response attributes. + +```bash +# create the demo namespace +kubectl create ns demo + +# deploy the httpbin application +kubectl apply -n demo -f https://raw.githubusercontent.com/istio/istio/master/samples/httpbin/httpbin.yaml +``` + +### Create a GatewayClass and a Gateway + +With Envoy Gateway installed we can now create a `Gateway`. To do so we will also create a dedicated `GatewayClass`. + +Depending on your setup you will potentially need to create an `EnvoyProxy` resource to customize the way Envoy Gateway will create the underlying `Service`. The script below creates one to set the name and type of the service because the kind cluster created in the first step doesn't come with load balancer support. + +```bash +# create a gateway +kubectl apply -n demo -f - < + size(variables.authorization) == 2 && variables.authorization[0].lowerAscii() == "bearer" + ? jwt.Decode(variables.authorization[1], "secret") + : null + authorizations: + # request not authenticated -> 401 + - expression: > + variables.token == null || !variables.token.Valid + ? envoy.Denied(401).Response() + : null + # request authenticated but not admin role -> 403 + - expression: > + variables.token.Claims.?role.orValue("") != "admin" + ? envoy.Denied(403).Response() + : null + # request authenticated and admin role -> 200 + - expression: > + envoy + .Allowed() + .WithHeader("x-validated-by", "my-security-checkpoint") + .WithoutHeader("x-force-authorized") + .WithResponseHeader("x-add-custom-response-header", "added") + .Response() +EOF +``` + +### Deploy an Envoy Gateway SecurityPolicy + +A `SecurityPolicy` is the custom Envoy Gateway resource to configure underlying Envoy Proxy to use an external auth server (the Kyverno Authz Server we installed in a prior step). + +```bash +# deploy envoy gateway security policy +kubectl apply -n demo -f - <