|
| 1 | +# Remote Infrastructure Provider Example |
| 2 | + |
| 3 | +This example is a reference implementation of the Envoy Gateway [Remote |
| 4 | +Infrastructure Provider][docs] gRPC service. It receives the Envoy Gateway |
| 5 | +Infrastructure IR over gRPC and reconciles a `Deployment` and a `Service` per |
| 6 | +proxy fleet against the Kubernetes API. |
| 7 | + |
| 8 | +It is the server used by the `e2e-remote-infra` test target and is intended as |
| 9 | +a starting point for writing your own provider — not a production-ready |
| 10 | +implementation. |
| 11 | + |
| 12 | +For the full conceptual model and a quickstart that wires this image into an |
| 13 | +Envoy Gateway install, see [the task documentation][docs]. |
| 14 | + |
| 15 | +## What it does |
| 16 | + |
| 17 | +The provider implements the four RPCs defined in |
| 18 | +[`proto/remoteinfra/service.proto`](../../proto/remoteinfra/service.proto): |
| 19 | + |
| 20 | +| RPC | Behavior | |
| 21 | +| ------------------------------ | ---------------------------------------------------------------- | |
| 22 | +| `CreateOrUpdateProxyInfra` | Reconciles a `Deployment` and `Service` for the IR's proxy fleet | |
| 23 | +| `DeleteProxyInfra` | Deletes the `Deployment` and `Service` for the IR's proxy fleet | |
| 24 | +| `CreateOrUpdateRateLimitInfra` | No-op. Rate limiting must be provisioned out of band, see below | |
| 25 | +| `DeleteRateLimitInfra` | No-op | |
| 26 | + |
| 27 | +The IR is delivered as JSON in the request's `ir_bytes` field. The example |
| 28 | +ignores fields it doesn't understand, which is the same forward-compatibility |
| 29 | +posture you'll want in your own provider. |
| 30 | + |
| 31 | +## Layout |
| 32 | + |
| 33 | +| Path | Purpose | |
| 34 | +| ------------------- | ------------------------------------------------------------------------ | |
| 35 | +| `main.go` | Binds a Unix domain socket and starts the gRPC server | |
| 36 | +| `synthesizer/` | Translates the IR into desired `Deployment` / `Service` objects | |
| 37 | +| `synthesizer/*.tpl` | Embedded Envoy bootstrap template | |
| 38 | +| `pb/` | Generated gRPC stubs (regenerated from the proto in this repo) | |
| 39 | +| `Dockerfile` | Builds the server image. Alpine base — see note below | |
| 40 | +| `Makefile` | `docker-buildx` target produces `envoyproxy/gateway-remote-infra:latest` | |
| 41 | + |
| 42 | +## Build |
| 43 | + |
| 44 | +```shell |
| 45 | +make docker-buildx |
| 46 | +``` |
| 47 | + |
| 48 | +If you're running on `kind`, load the image into the cluster: |
| 49 | + |
| 50 | +```shell |
| 51 | +kind load docker-image --name envoy-gateway envoyproxy/gateway-remote-infra:latest |
| 52 | +``` |
| 53 | + |
| 54 | +## Run |
| 55 | + |
| 56 | +The expected deployment shape is as a native sidecar of the `envoy-gateway` |
| 57 | +Pod, sharing an `emptyDir` volume that holds the UDS. The full patch is in |
| 58 | +`test/e2e/remote_infra/sidecar-patch.yaml` and is documented in [the task |
| 59 | +guide][docs]. By default the server listens on |
| 60 | +`/var/run/remote-infra/server.sock` with mode `0660`; both are tunable via |
| 61 | +flags: |
| 62 | + |
| 63 | +```text |
| 64 | +--socket-path=/var/run/remote-infra/server.sock |
| 65 | +--socket-mode=0660 |
| 66 | +``` |
| 67 | + |
| 68 | +The `NAMESPACE` environment variable selects which Kubernetes namespace the |
| 69 | +provider writes resources into. The sidecar patch wires this to the Pod's own |
| 70 | +namespace via the downward API. |
| 71 | + |
| 72 | +## Limitations |
| 73 | + |
| 74 | +This is a teaching example, not a production provider. In particular: |
| 75 | + |
| 76 | +- It only renders one Deployment and one Service per IR. Real providers will |
| 77 | + often want a HorizontalPodAutoscaler, PodDisruptionBudget, and so on. |
| 78 | +- It does not provision rate limit infrastructure. |
| 79 | +- It does not surface reconcile errors back to Envoy Gateway through the gRPC |
| 80 | + response in a structured way; errors are returned as plain strings. |
0 commit comments