From 79805b5b7c0075d4c7216ee6104dd794a9120053 Mon Sep 17 00:00:00 2001 From: Denis Shatokhin Date: Wed, 29 Jan 2025 21:36:20 +0200 Subject: [PATCH 1/2] docs: add standalone in container instruction Signed-off-by: Denis Shatokhin --- .../standalone/quickstart-containers.yaml | 46 +++++++ .../operations/standalone-deployment-mode.md | 130 +++++++++++++++++- 2 files changed, 174 insertions(+), 2 deletions(-) create mode 100644 examples/standalone/quickstart-containers.yaml diff --git a/examples/standalone/quickstart-containers.yaml b/examples/standalone/quickstart-containers.yaml new file mode 100644 index 00000000000..1468219c804 --- /dev/null +++ b/examples/standalone/quickstart-containers.yaml @@ -0,0 +1,46 @@ +apiVersion: gateway.networking.k8s.io/v1 +kind: GatewayClass +metadata: + name: eg +spec: + controllerName: gateway.envoyproxy.io/gatewayclass-controller +--- +apiVersion: gateway.networking.k8s.io/v1 +kind: Gateway +metadata: + name: eg +spec: + gatewayClassName: eg + listeners: + - name: http + protocol: HTTP + port: 8888 +--- +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: backend +spec: + parentRefs: + - name: eg + hostnames: + - "www.example.com" + rules: + - backendRefs: + - group: "gateway.envoyproxy.io" + kind: Backend + name: backend + matches: + - path: + type: PathPrefix + value: / +--- +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: Backend +metadata: + name: backend +spec: + endpoints: + - fqdn: + hostname: local-server.local + port: 3000 diff --git a/site/content/en/latest/tasks/operations/standalone-deployment-mode.md b/site/content/en/latest/tasks/operations/standalone-deployment-mode.md index 88a5c1b98c2..6520508cb83 100644 --- a/site/content/en/latest/tasks/operations/standalone-deployment-mode.md +++ b/site/content/en/latest/tasks/operations/standalone-deployment-mode.md @@ -16,7 +16,7 @@ Currently, Envoy Gateway only support the file provider and the host infrastruct - The file provider will configure the Envoy Gateway to get all gateway-api resources from file system. - The host infrastructure provider will configure the Envoy Gateway to deploy one Envoy Proxy as a host process. -## Quick Start +## Quick Start Locally In this quick-start, we will run Envoy Gateway in standalone mode with the file provider and the host infrastructure provider. @@ -40,7 +40,7 @@ The compiled binary lies in `bin/{os}/{arch}/envoy-gateway`. ### Create Certificates -All runners in Envoy Gateway are using TLS connection, so create these TLS certificates locally to +All runners in Envoy Gateway are using TLS connection, so create these TLS certificates locally to ensure the Envoy Gateway works properly. ```shell @@ -126,5 +126,131 @@ curl --verbose --header "Host: www.example.com" http://0.0.0.0:8888/ * Connection #0 to host 0.0.0.0 left intact ``` +## Quick Start in a Container + +In this quick-start, we will run Envoy Gateway in standalone mode with the file provider +and the host infrastructure provider. + +### Prerequisites + +Create a local directory just for testing: + +```shell +mkdir -p /tmp/envoy-gateway-test/config +chmod -R 777 /tmp/envoy-gateway-test +``` + +Create a container network to run Envoy Gateway and a local server: + +```shell +docker network create envoy-gateway-test +``` + +It's important to widen permissions of a created directory to avoid `Permission denied` error + +### Create Certificates + +All runners in Envoy Gateway are using TLS connection, so create these TLS certificates locally to +ensure the Envoy Gateway works properly. + +```shell +docker run --rm --volume /tmp/envoy-gateway-test:/tmp/envoy-gateway envoyproxy/gateway:v1.3.0-rc.1 certgen --local +``` + +### Start Envoy Gateway + +The following configuration should be placed into `/tmp/envoy-gateway-test/standalone.yaml` on the host: + +```yaml +apiVersion: gateway.envoyproxy.io/v1alpha1 +kind: EnvoyGateway +gateway: + controllerName: gateway.envoyproxy.io/gatewayclass-controller +provider: + type: Custom + custom: + resource: + type: File + file: + paths: ["/tmp/envoy-gateway/config"] + infrastructure: + type: Host + host: {} +logging: + level: + default: info +extensionApis: + enableBackend: true +``` + +Start Envoy Gateway by the following command: + +```shell +$ docker run \ + --name envoy-gateway \ + --network envoy-gateway-test \ + --publish 8888:8888 \ + --volume /tmp/envoy-gateway-test:/tmp/envoy-gateway \ + --detach \ + envoyproxy/gateway:v1.3.0-rc.1 \ + server --config-path /tmp/envoy-gateway/standalone.yaml +``` + +As you can see, we have enabled the [Backend][] API, this API will be used to represent our local endpoints. + +### Trigger an Update + +Any changes under watched `paths` will be considered as an update by the file provider. + +For instance, copying example file into `/tmp/envoy-gateway/config` will trigger an update of gateway-api resources: + +```shell +cp examples/standalone/quickstart-containers.yaml /tmp/envoy-gateway-test/config/ +``` + +From the Envoy Gateway log, you should be able to observe that the Envoy Proxy has been started, and its admin address has been returned. + +### Test Connection + +Starts a simple local server in a same container network: + +```shell +$ docker run \ + --name local-server \ + --hostname local-server.local \ + --network envoy-gateway-test \ + --detach \ + python:3 \ + python3 -m http.server 3000 +``` + +The `--hostname` field values is used in `Backend` object of Envoy Gateway as FQDN. +This way there is no need to update `Backend` object if IP address of container changed. + +Curl the example server through Envoy Proxy: + +```shell +curl --verbose --header "Host: www.example.com" http://0.0.0.0:8888/ +``` + +```console +* Trying 0.0.0.0:8888... +* Connected to 0.0.0.0 (0.0.0.0) port 8888 +* using HTTP/1.x +> GET / HTTP/1.1 +> Host: www.example.com +> User-Agent: curl/8.11.1 +> Accept: */* +> +* Request completely sent off +< HTTP/1.1 200 OK +< server: SimpleHTTP/0.6 Python/3.13.1 +< date: Wed, 29 Jan 2025 17:04:11 GMT +< content-type: text/html; charset=utf-8 +< content-length: 877 +< +... +* Connection #0 to host 0.0.0.0 left intact +``` [Backend]: ../../../api/extension_types#backend From 6d4b769539cb963df5d3bb99e6881e0241d40e4f Mon Sep 17 00:00:00 2001 From: Denis Shatokhin Date: Thu, 30 Jan 2025 21:42:29 +0200 Subject: [PATCH 2/2] docs: update headings and image tag Signed-off-by: Denis Shatokhin --- .../tasks/operations/standalone-deployment-mode.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/site/content/en/latest/tasks/operations/standalone-deployment-mode.md b/site/content/en/latest/tasks/operations/standalone-deployment-mode.md index 6520508cb83..102ad33238e 100644 --- a/site/content/en/latest/tasks/operations/standalone-deployment-mode.md +++ b/site/content/en/latest/tasks/operations/standalone-deployment-mode.md @@ -16,7 +16,9 @@ Currently, Envoy Gateway only support the file provider and the host infrastruct - The file provider will configure the Envoy Gateway to get all gateway-api resources from file system. - The host infrastructure provider will configure the Envoy Gateway to deploy one Envoy Proxy as a host process. -## Quick Start Locally +# Quick Start + +## Running locally on the host machine In this quick-start, we will run Envoy Gateway in standalone mode with the file provider and the host infrastructure provider. @@ -126,7 +128,7 @@ curl --verbose --header "Host: www.example.com" http://0.0.0.0:8888/ * Connection #0 to host 0.0.0.0 left intact ``` -## Quick Start in a Container +## Running in a Container In this quick-start, we will run Envoy Gateway in standalone mode with the file provider and the host infrastructure provider. @@ -154,7 +156,7 @@ All runners in Envoy Gateway are using TLS connection, so create these TLS certi ensure the Envoy Gateway works properly. ```shell -docker run --rm --volume /tmp/envoy-gateway-test:/tmp/envoy-gateway envoyproxy/gateway:v1.3.0-rc.1 certgen --local +docker run --rm --volume /tmp/envoy-gateway-test:/tmp/envoy-gateway envoyproxy/gateway:{{< helm-version >}} certgen --local ``` ### Start Envoy Gateway @@ -192,7 +194,7 @@ $ docker run \ --publish 8888:8888 \ --volume /tmp/envoy-gateway-test:/tmp/envoy-gateway \ --detach \ - envoyproxy/gateway:v1.3.0-rc.1 \ + envoyproxy/gateway:{{< helm-version >}} \ server --config-path /tmp/envoy-gateway/standalone.yaml ```