Merge pull request #1 from solo-io/first-example

Add basic-sink example

.gitignore

@@ -0,0 +1,2 @@
+.vscode
+.idea

README.md

@@ -1 +1,5 @@
-# ext-proc-examples
+# External Processing examples
+
+Example gRPC services that implement the interface used by Envoy's [External Processing filter](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/ext_proc_filter)
+
+Currently the examples in this repo are only used for [Gloo Edge](https://github.com/solo-io/solo-projects) end-to-end tests.

basic-sink/.gitignore

@@ -0,0 +1 @@
+_output

basic-sink/Dockerfile

@@ -0,0 +1,12 @@
+FROM golang:alpine AS builder
+
+RUN apk --no-cache add make
+WORKDIR /app
+COPY . .
+
+FROM alpine
+RUN ls
+COPY ./_output/server /server
+
+EXPOSE 18080
+CMD ["./server"]

basic-sink/Makefile

@@ -0,0 +1,21 @@
+# this is the latest tag that has been pushed
+# if changes are made to the service, this tag should be updated before pushing
+TAG ?= 0.0.1
+
+.PHONY: docker-local server
+all: server docker-local
+
+server:
+	CGO_ENABLED=0 GOOS=linux go build -a -o _output/server
+
+docker-local: server
+	docker build -t gcr.io/solo-test-236622/ext-proc-example-basic-sink:$(TAG) .
+
+docker-push:
+	./publish-interactive.sh $(TAG)
+
+run:
+	docker run -p 18080:18080 gcr.io/solo-test-236622/ext-proc-example-basic-sink:$(TAG)
+
+clean:
+	rm -fr _output/server

basic-sink/README.md

@@ -0,0 +1,89 @@
+# Basic Sink
+
+## Usage
+
+This is an example external processing service that takes instructions in a request or response header
+named `instructions`. The value of the `instructions` header must be a JSON string in the format:
+```
+{
+  "addHeaders": {
+    "header1": "value1",
+    "header2": "value2"
+  },
+  "removeHeaders": [ "header3", "header4" ],
+  "setBody": "this is the new body",
+  "setTrailers": {
+    "trailer1": "value1",
+    "trailer2": "value2"
+  }
+}
+```
+All fields are optional. See the `Instructions` struct in [main.go](./main.go) for details on the meaning of each field.
+
+Note that these instructions need to come as part of the `Headers` field of a `RequestHeaders` or `ResponseHeaders`
+[ProcessingRequest](https://www.envoyproxy.io/docs/envoy/latest/api-v3/service/ext_proc/v3/external_processor.proto#service-ext-proc-v3-processingrequest). Therefore, the instructions will only be received/processed if the
+request or response header processing mode is set to `SEND` (or `DEFAULT` since the default for headers is `SEND`).
+
+*Modifying the body or trailers has not been tested and may not work as expected.*
+
+## Compatibility
+
+This sample app currently depends on a `go-control-plane` fork based on envoy changes that have not been merged upstream. It has been tested to work with Gloo Edge 1.15.x (which contains the same go-control-plane dependency) but may not work with newer versions of Gloo Edge.
+
+## Building Locally
+
+To build and use the service locally:
+1. Create a kind cluster: `kind create cluster --name <cluster>`
+1. Compile the extproc service using: `make TAG=<tag> all`
+1. Load onto kind cluster: `kind load docker-image gcr.io/solo-test-236622/ext-proc-example-basic-sink:<tag> --name <cluster>`
+
+## Publishing New Versions
+
+The basic-sink service is currently published as image `gcr.io/solo-test-236622/ext-proc-example-basic-sink:<TAG>`
+and used in Gloo Edge e2e tests.
+
+To make changes to the service:
+1. Update the `TAG` in the Makefile to a new version.
+1. Run `make all docker-push`, which will compile and publish a new version of the image to gcr.io. *Make sure you update the TAG before running this, so you don't overwrite an existing tag that is being used in e2e tests!*
+1. Update e2e tests to use the new tag.
+
+## Example Configuration in Gloo Edge
+
+The [resources](./resources) folder contains example configuration for setting up Gloo Edge
+to use the external processing service. To demonstrate a simple setup, you can either run the script [basic-demo.sh](./basic-demo.sh) or follow the steps one-by-one below:
+
+1. Create a kind cluster:
+```
+kind create cluster --name <cluster>
+```
+2. Install a recent version of Gloo Edge, with a values file that initializes extproc settings:
+```
+helm install -n gloo-system gloo-ee gloo-ee/gloo-ee --create-namespace --set-string license_key=$GLOO_LICENSE_KEY --set gloo-fed.enabled=false --version v1.15.2 -f resources/values.yaml
+```
+
+3. Apply the Deployment and Service for the extproc service (note that if you are using a locally-built image, you may need to change the image tag in the below yaml before applying it):
+```
+kubectl apply -f resources/extproc.yaml
+```
+4. Create a VirtualService that routes to httpbin:
+```
+kubectl apply -f resources/httpbin.yaml
+kubectl apply -f resources/vs.yaml
+```
+
+Now you can send traffic through the VS, with extproc instructions in the header:
+```
+kubectl port-forward -n gloo-system deploy/gateway-proxy 8080
+
+curl -v localhost:8080/get -H "header1: value1" -H "header2: value2" -H 'instructions: {"addHeaders":{"header3":"value3","header4":"value4"},"removeHeaders":["instructions", "header2"]}'
+```
+This should result in a response showing headers similar to the following (`header3` and `header4` were added; `header2` and `instructions` were removed):
+```
+  "headers": {
+    ...
+    "Header1": "value1",
+    "Header3": "value3",
+    "Header4": "value4",
+    ...
+  }
+```

basic-sink/basic-demo.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+
+set -e
+
+CLUSTER=test
+GLOO_EE_VERSION=v1.15.2
+
+# Create a kind cluster:
+kind create cluster --name $CLUSTER
+
+# Install a recent version of Gloo Edge, with a values file that initializes extproc settings:
+helm install -n gloo-system gloo-ee gloo-ee/gloo-ee --create-namespace --set-string license_key=$GLOO_LICENSE_KEY --set gloo-fed.enabled=false --version $GLOO_EE_VERSION -f resources/values.yaml
+
+# Apply the Deployment and Service for the extproc service (note that if you are using a locally-built image, you may need to change the image tag in the below yaml before applying it):
+kubectl apply -f resources/extproc.yaml
+
+# Create a VirtualService that routes to httpbin:
+kubectl apply -f resources/httpbin.yaml
+kubectl apply -f resources/vs.yaml

basic-sink/go.mod

@@ -0,0 +1,26 @@
+module github.com/solo-io/ext-proc-examples/basic-sink
+
+go 1.20
+
+require (
+	github.com/envoyproxy/go-control-plane v0.11.1
+	github.com/golang/protobuf v1.5.3
+	github.com/solo-io/go-utils v0.24.6
+	google.golang.org/grpc v1.58.1
+	google.golang.org/protobuf v1.31.0
+)
+
+require (
+	github.com/cncf/xds/go v0.0.0-20230607035331-e9ce68804cb4 // indirect
+	github.com/envoyproxy/protoc-gen-validate v1.0.2 // indirect
+	github.com/k0kubun/pp v3.0.1+incompatible // indirect
+	github.com/mattn/go-colorable v0.1.13 // indirect
+	github.com/mattn/go-isatty v0.0.19 // indirect
+	golang.org/x/net v0.15.0 // indirect
+	golang.org/x/sys v0.12.0 // indirect
+	golang.org/x/text v0.13.0 // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20230913181813-007df8e322eb // indirect
+)
+
+// Remove once we get to a version with extproc changes in upstream envoy 1.28
+replace github.com/envoyproxy/go-control-plane => github.com/solo-io/go-control-plane-fork-v2 v0.0.0-20230902211618-ada8201b381c