From 296230d89e95f332b1072b85477fc8c74a967bac Mon Sep 17 00:00:00 2001 From: Rae Sharp Date: Mon, 8 Dec 2025 10:45:16 -0500 Subject: [PATCH 01/10] Add ingress-nginx migration docs --- .../self-hosted/ingress-nginx-migration.md | 266 ++++++++++++++++++ .../self-hosted-spaces-deployment.md | 151 +++++++--- 2 files changed, 381 insertions(+), 36 deletions(-) create mode 100644 docs/manuals/spaces/howtos/self-hosted/ingress-nginx-migration.md diff --git a/docs/manuals/spaces/howtos/self-hosted/ingress-nginx-migration.md b/docs/manuals/spaces/howtos/self-hosted/ingress-nginx-migration.md new file mode 100644 index 000000000..e3e606298 --- /dev/null +++ b/docs/manuals/spaces/howtos/self-hosted/ingress-nginx-migration.md @@ -0,0 +1,266 @@ +--- +title: Migrate to Envoy Gateway +sidebar_position: 6 +description: A guide on how to migrate to Envoy Gateway from ingress-nginx +tier: "business" +--- +import GlobalLanguageSelector, { CodeBlock } from '@site/src/components/GlobalLanguageSelector'; + + + + +Upbound recommends migrating from the Ingress API to the Gateway API for routing +traffic to control planes. This changes addresses critical security issues and +aligns with the Kuberenetes community decision to retire ingress-nginx in March +2026. + +## Why? + +Currently, TLS connections terminate at the ingress-nginx controller, but client +certificate validation happens later at the `spaces-router` component. The +controller extracts the certificate and forwards it in the `ssl-client-cert` +HTTP header. This presents a security flaw as the TLS handshake and certificate +validation are separate. + +With TLS passthrough mode, the encrypted connection goes directly to the +`spaces-router` component. Both the TLS handshake and certificate validation +happen together and eliminates the security vulnerability. + +Gateway API is also the official routing standard for Kubernetes going forward. + +## How? + +To migrate from ingress-nginx to Envoy Gateway, you must delete your current +ingress resource and controller and install the Gateway API implementation with +TLS passthrough enabled. + + +### 1. Remove existing Ingress resources + +Delete the Ingress resource and ingress-nginx controller: + +```bash +kubectl -n upbound-system delete ingress mxe-router-ingress +helm -n ingress-nginx delete ingress-nginx +``` + +:::warning +This step forces downtime for API access through spaces-router until the +Gateway API configuration is complete. +::: + +### 2. Install a Gateway API controller + +Install a Gateway API implementation that supports TLS passthrough and `TLSRoute`. +The following example uses Envoy Gateway: + +```bash +export ENVOY_GATEWAY_VERSION=v1.2.4 + +helm -n envoy-gateway-system upgrade --install --wait --wait-for-jobs \ + --timeout 300s --create-namespace envoy-gateway \ + oci://docker.io/envoyproxy/gateway-helm \ + --version "${ENVOY_GATEWAY_VERSION}" +``` + +### 3. Create GatewayClass resource + +Create a `GatewayClass` resource appropriate for your cloud provider. + + + +```bash +kubectl apply -f - --server-side < + + + + +```bash +kubectl apply -f - --server-side < + + + +```bash +kubectl apply -f - --server-side < + + +### 4. Create Gateway resource + +Create a Gateway resource in the `upbound-system` namespace. + + + +```bash +kubectl apply -f - --server-side < + + + + +```bash +kubectl apply -f - --server-side < + + + + + + +```bash +kubectl apply -f - --server-side < + + + +:::note +During installation or upgrade, you can use the Spaces Helm chart to create the +Gateway automatically with these parameters: +- `gatewayAPI.gateway.provision=true` +- `gatewayAPI.gateway.className=spaces` +::: + + +### 5. Get the load balancer hostname + +Check the externally routable hostname for the Gateway's load balancer. +The Helm `gatewayAPI.host` parameter requires this hostname. + +For Envoy Gateway, inspect the LoadBalancer service: + +```bash +kubectl get service -n envoy-gateway-system \ + -l gateway.envoyproxy.io/owning-gateway-name=spaces \ + -o jsonpath='{.items[0].status.loadBalancer.ingress[0].hostname}' +``` + +### 6. Upgrade the Spaces Helm release + +Upgrade the Spaces installation with Gateway API parameters: + +```bash +helm -n upbound-system upgrade spaces \ + oci://xpkg.upbound.io/spaces-artifacts/spaces \ + --version "${SPACES_VERSION}" \ + --set "ingress.provision=false" \ + --set "gatewayAPI.host=${GATEWAY_HOSTNAME}" \ + --set "account=${UPBOUND_ACCOUNT}" \ + --reuse-values \ + --wait +``` + +### 7. Restart spaces-router (Optional) + +If the `gatewayAPI.host` value differs from the previous `ingress.host` value, +restart the spaces-router pod to regenerate the certificate with the correct SAN +(Subject Alternative Name): + +```bash +kubectl -n upbound-system rollout restart deployment spaces-router +kubectl -n upbound-system rollout status deployment spaces-router +``` + +## Additional resources + +- [Spaces Deployment] +- [Kubernetes Announcement] + +[spaces deployment]: +/manuals/spaces/howtos/self-hosted/self-hosted-spaces-deployment +[kubernetes announcement]: https://www.kubernetes.dev/blog/2025/11/12/ingress-nginx-retirement/ diff --git a/docs/manuals/spaces/howtos/self-hosted/self-hosted-spaces-deployment.md b/docs/manuals/spaces/howtos/self-hosted/self-hosted-spaces-deployment.md index e549e3939..230aa2411 100644 --- a/docs/manuals/spaces/howtos/self-hosted/self-hosted-spaces-deployment.md +++ b/docs/manuals/spaces/howtos/self-hosted/self-hosted-spaces-deployment.md @@ -1,7 +1,7 @@ --- title: Deployment Workflow sidebar_position: 3 -description: A quickstart guide for Upbound Spaces +description: A quickstart guide for Upbound Spaces tier: "business" --- import GlobalLanguageSelector, { CodeBlock } from '@site/src/components/GlobalLanguageSelector'; @@ -249,59 +249,135 @@ helm install aws-load-balancer-controller aws-load-balancer-controller --namespa -### Install ingress-nginx +### Install Envoy Gateway -Starting with Spaces v1.10.0, you need to configure the ingress-nginx -controller to allow SSL-passthrough mode. You can do so by passing the -`--enable-ssl-passthrough=true` command-line option to the controller. -The following Helm install command enables this with the `controller.extraArgs` -parameter: +Starting with Spaces v1.10.0, Upbound recommends using the [Gateway API] for +routing traffic to Spaces. Gateway API is the official Kubernetes standard for +ingress and replaces the legacy Ingress API. + +This guide uses Envoy Gateway as the Gateway API controller and replaces +ingress-nginx previously recommended. + +:::info +If you need to continue to use ingress-nginx temporarily, use the [ingress-nginx +migration guide][migration guide]. + +The Kubernetes community announced that ingress-nginx will be retired in March +2026 and you should plan to migrate to Gateway API before then. +::: + + +First, install Envoy Gateway with Helm: + +```bash +helm -n envoy-gateway-system upgrade --install --wait --wait-for-jobs \ + --timeout 360s --create-namespace envoy-gateway \ + oci://docker.io/envoyproxy/gateway-helm \ + --version "v1.2.4" +``` + +Next, create the Gateway API resources for your cloud provider: +Create EnvoyProxy configuration for AWS load balancer + ```bash -helm upgrade --install ingress-nginx ingress-nginx \ - --create-namespace --namespace ingress-nginx \ - --repo https://kubernetes.github.io/ingress-nginx \ - --version 4.12.1 \ - --set 'controller.service.type=LoadBalancer' \ - --set 'controller.extraArgs.enable-ssl-passthrough=true' \ - --set 'controller.service.annotations.service\.beta\.kubernetes\.io/aws-load-balancer-type=external' \ - --set 'controller.service.annotations.service\.beta\.kubernetes\.io/aws-load-balancer-scheme=internet-facing' \ - --set 'controller.service.annotations.service\.beta\.kubernetes\.io/aws-load-balancer-nlb-target-type=ip' \ - --set 'controller.service.annotations.service\.beta\.kubernetes\.io/aws-load-balancer-healthcheck-protocol=http' \ - --set 'controller.service.annotations.service\.beta\.kubernetes\.io/aws-load-balancer-healthcheck-path=/healthz' \ - --set 'controller.service.annotations.service\.beta\.kubernetes\.io/aws-load-balancer-healthcheck-port=10254' \ - --wait +kubectl apply -f - --server-side < +```bash +Create EnvoyProxy configuration for Azure load balancer: ```bash -helm upgrade --install ingress-nginx ingress-nginx \ - --create-namespace --namespace ingress-nginx \ - --repo https://kubernetes.github.io/ingress-nginx \ - --version 4.12.1 \ - --set 'controller.service.type=LoadBalancer' \ - --set 'controller.extraArgs.enable-ssl-passthrough=true' \ - --set 'controller.service.annotations.service\.beta\.kubernetes\.io/azure-load-balancer-health-probe-request-path=/healthz' \ - --wait +kubectl apply -f - --server-side < +Create GatewayClass: ```bash -helm upgrade --install ingress-nginx ingress-nginx \ - --create-namespace --namespace ingress-nginx \ - --repo https://kubernetes.github.io/ingress-nginx \ - --version 4.12.1 \ - --set 'controller.service.type=LoadBalancer' \ - --set 'controller.extraArgs.enable-ssl-passthrough=true' \ - --wait +kubectl apply -f - --server-side < @@ -375,7 +451,10 @@ kubectl get ingress \ -If the preceding command doesn't return a load balancer address then your provider may not have allocated it yet. Once it's available, add a DNS record for the `ROUTER_HOST` to point to the given load balancer address. If it's an IPv4 address, add an A record. If it's a domain name, add a CNAME record. +If the preceding command doesn't return a load balancer address then your +provider may not have allocated it yet. Once it's available, add a DNS record +for the `ROUTER_HOST` to point to the given load balancer address. If it's an +IPv4 address, add an A record. If it's a domain name, add a CNAME record. ## Configure the up CLI From 79497cf3bdde8d7268dc36653b120a312a99e34a Mon Sep 17 00:00:00 2001 From: rae sharp <8883519+tr0njavolta@users.noreply.github.com> Date: Wed, 17 Dec 2025 11:40:57 -0500 Subject: [PATCH 02/10] Update docs/manuals/spaces/howtos/self-hosted/ingress-nginx-migration.md Signed-off-by: rae sharp <8883519+tr0njavolta@users.noreply.github.com> --- .../howtos/self-hosted/ingress-nginx-migration.md | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/docs/manuals/spaces/howtos/self-hosted/ingress-nginx-migration.md b/docs/manuals/spaces/howtos/self-hosted/ingress-nginx-migration.md index e3e606298..389446b68 100644 --- a/docs/manuals/spaces/howtos/self-hosted/ingress-nginx-migration.md +++ b/docs/manuals/spaces/howtos/self-hosted/ingress-nginx-migration.md @@ -14,19 +14,6 @@ traffic to control planes. This changes addresses critical security issues and aligns with the Kuberenetes community decision to retire ingress-nginx in March 2026. -## Why? - -Currently, TLS connections terminate at the ingress-nginx controller, but client -certificate validation happens later at the `spaces-router` component. The -controller extracts the certificate and forwards it in the `ssl-client-cert` -HTTP header. This presents a security flaw as the TLS handshake and certificate -validation are separate. - -With TLS passthrough mode, the encrypted connection goes directly to the -`spaces-router` component. Both the TLS handshake and certificate validation -happen together and eliminates the security vulnerability. - -Gateway API is also the official routing standard for Kubernetes going forward. ## How? From b31a1636916eda141f693b1a60ac4df1d016676c Mon Sep 17 00:00:00 2001 From: Rae Sharp Date: Tue, 27 Jan 2026 18:11:40 -0500 Subject: [PATCH 03/10] Update with new info and options --- .../self-hosted/ingress-nginx-migration.md | 599 ++++++++++++++++-- .../spaces/howtos/self-hosted/ingress.md | 134 ++++ .../styles/Upbound/spelling-exceptions.txt | 8 + 3 files changed, 704 insertions(+), 37 deletions(-) create mode 100644 docs/manuals/spaces/howtos/self-hosted/ingress.md diff --git a/docs/manuals/spaces/howtos/self-hosted/ingress-nginx-migration.md b/docs/manuals/spaces/howtos/self-hosted/ingress-nginx-migration.md index 389446b68..7088ad2d3 100644 --- a/docs/manuals/spaces/howtos/self-hosted/ingress-nginx-migration.md +++ b/docs/manuals/spaces/howtos/self-hosted/ingress-nginx-migration.md @@ -1,28 +1,433 @@ --- -title: Migrate to Envoy Gateway -sidebar_position: 6 -description: A guide on how to migrate to Envoy Gateway from ingress-nginx +title: Migrate away from ingress-nginx +sidebar_position: 7 +description: A guide on how to migrate from ingress-nginx tier: "business" --- + import GlobalLanguageSelector, { CodeBlock } from '@site/src/components/GlobalLanguageSelector'; +`ingress-nginx` is deprecated and will reach end-of-life in March 2026. This +guide covers migration options for existing Spaces deployments. + +For help choosing an exposure method, see [Exposing Spaces Externally][expose]. + +Options vary by Spaces version. Select your Spaces version: + +* [Upgrading to Spaces 1.16+](#upgrading-to-spaces-116) +* [Cannot upgrade before March 2026](#cant-upgrade-to-spaces-116-before-march-2026) + + + +## Prerequisites + +Set environment variables used throughout this guide: + +```bash +export SPACES_VERSION= # Example: 1.16.0 +export SPACES_ROUTER_HOST= # Example: proxy.example.com +``` + +Export your current Helm values to a file (or use an existing version-controlled +file): + +```bash +helm get values spaces -n upbound-system -o yaml > values.yaml +``` + +You'll merge new configuration into this file throughout the migration. + +## Upgrading to Spaces 1.16+ + +Choose your migration option: + +| Option | When to use | +|--------|-------------| +| [LoadBalancer Service](#loadbalancer-service-recommended) | Simplest setup, no additional components needed | +| [Gateway API](#gateway-api) | Already using Gateway API or need shared gateway | +| [Alternative ingress controller](#alternative-ingress-controller) | Already using Ingress, or need shared load balancer | + +All paths follow the same process: upgrade to 1.16+, switch exposure method, +then uninstall ingress-nginx. + +### Upgrade to 1.16+ with Updated Ingress Values + +Spaces doesn't provision the Ingress resource by default and is now +controller-agnostic. + +Add the following to your `values.yaml` to keep ingress-nginx working: + +```yaml +ingress: + provision: true + host: proxy.example.com # Replace with your existing hostname + ingressClassName: nginx + annotations: + nginx.ingress.kubernetes.io/ssl-passthrough: "true" + nginx.ingress.kubernetes.io/backend-protocol: "HTTPS" + podLabels: + app.kubernetes.io/name: ingress-nginx + app.kubernetes.io/component: controller + namespaceLabels: + kubernetes.io/metadata.name: ingress-nginx +``` + +Upgrade Spaces to 1.16+: + +```bash +helm upgrade spaces oci://xpkg.upbound.io/spaces-artifacts/spaces \ + --version ${SPACES_VERSION} \ + --namespace upbound-system \ + -f values.yaml \ + --wait +``` + +Verify ingress-nginx is still working before you contine. + +### LoadBalancer Service (Recommended) + +This section describes how to expose the `spaces-router` with a LoadBalancer +Service. + +:::important +Use a Network Load Balancer (L4), not an Application Load Balancer (L7). Spaces +uses long-lived connections for watch traffic that L7 load balancers may +timeout. +::: -Upbound recommends migrating from the Ingress API to the Gateway API for routing -traffic to control planes. This changes addresses critical security issues and -aligns with the Kuberenetes community decision to retire ingress-nginx in March -2026. +**1. Add the LoadBalancer Service configuration to your `values.yaml`** + +```yaml +externalTLS: + host: proxy.example.com # Must match your ingress.host + +router: + proxy: + service: + type: LoadBalancer + annotations: + # AWS NLB (see Cloud-Specific Annotations for other clouds) + service.beta.kubernetes.io/aws-load-balancer-type: external + service.beta.kubernetes.io/aws-load-balancer-scheme: internet-facing + service.beta.kubernetes.io/aws-load-balancer-nlb-target-type: ip +``` +:::note +This example uses AWS-specific annotations. See [Cloud-Specific Annotations for GCP and Azure][expose-annotate]. +::: -## How? +**2. Upgrade Spaces (Ingress stays running during transition)** -To migrate from ingress-nginx to Envoy Gateway, you must delete your current -ingress resource and controller and install the Gateway API implementation with -TLS passthrough enabled. +```bash +helm upgrade spaces oci://xpkg.upbound.io/spaces-artifacts/spaces \ + --version ${SPACES_VERSION} \ + --namespace upbound-system \ + -f values.yaml \ + --wait +``` +**3. Get the new LoadBalancer address** -### 1. Remove existing Ingress resources +```bash +kubectl get svc -n upbound-system spaces-router \ + -o jsonpath='{.status.loadBalancer.ingress[0].hostname}' +``` + +**4. Validate before switching DNS** + +```bash +# Get spaces-router load balancer address +ROUTER_LB=$(kubectl get svc -n upbound-system spaces-router -o jsonpath='{.status.loadBalancer.ingress[0].hostname}') + +# Test connectivity using --connect-to to route to the new LB +curl --connect-to "${SPACES_ROUTER_HOST}:443:${ROUTER_LB}:443" "https://${SPACES_ROUTER_HOST}/version" +# Expected: 401 Unauthorized (routing works, auth required) +``` + +**5. Update your DNS record to point to the new LoadBalancer address** + +**6. Update your `values.yaml` to disable Ingress, then upgrade Spaces** + +```yaml +ingress: + provision: false +``` + +```bash +helm upgrade spaces oci://xpkg.upbound.io/spaces-artifacts/spaces \ + --version ${SPACES_VERSION} \ + --namespace upbound-system \ + -f values.yaml \ + --wait +``` + +**7. Uninstall ingress-nginx** + +```bash +helm uninstall ingress-nginx --namespace ingress-nginx +``` + +### Gateway API + +Spaces supports the [Gateway API][gateway-api] as an alternative to Ingress. Gateway API is the +Kubernetes standard for traffic routing going forward. + + +**1. Install Envoy Gateway** + +```bash +helm install eg oci://docker.io/envoyproxy/gateway-helm \ + --namespace envoy-gateway-system \ + --create-namespace \ + --wait +``` + +See [Envoy Gateway installation docs][envoy-install] for more detailed instructions. + +**2. Create a GatewayClass** + +Create a `GatewayClass` resource appropriate for your cloud provider. + + + +```bash +kubectl apply -f - --server-side < + + + +```bash +kubectl apply -f - --server-side < + + + +```bash +kubectl apply -f - --server-side < + +**3. Configure Spaces Helm Values** + +```yaml +ingress: + provision: false # Disable Ingress when using Gateway API + +gatewayAPI: + host: proxy.example.com + gateway: + provision: true + name: spaces + className: spaces + spacesRouterRoute: + provision: true + podLabels: + app.kubernetes.io/name: envoy + app.kubernetes.io/component: proxy + app.kubernetes.io/managed-by: envoy-gateway + namespaceLabels: + kubernetes.io/metadata.name: envoy-gateway-system +``` + +**4. Install or Upgrade Spaces** + +See [Spaces installation docs][spaces-install] for detailed installation instructions. + +```bash +helm upgrade spaces oci://xpkg.upbound.io/spaces-artifacts/spaces \ + --namespace upbound-system \ + -f values.yaml \ + --wait +``` + +**5. Get the Gateway Address** + +```bash +kubectl get gateway -n upbound-system spaces \ + -o jsonpath='{.status.addresses[0].value}' +``` + +Create or update a DNS record pointing your `gatewayAPI.host` to this address. + + +:::note +If you're having issues with your setup, verify the configuration with these +troubleshooting steps: + +* **Check Gateway Status** + + ```bash + kubectl get gateway -n upbound-system spaces -o yaml + ``` + + Look for `status.conditions` - the Gateway should be `Accepted` and `Programmed`. + +* **Check TLSRoute Status** + + ```bash + kubectl get tlsroute -n upbound-system spaces-router -o yaml + ``` + + The route should show `Accepted: True` in its status. + +* **Verify Connectivity** + + ```bash + curl -k "https://${SPACES_ROUTER_HOST}/version" + # Expected: 401 Unauthorized (routing works, auth required) + ``` +::: + +**6. Validate before switching DNS** + +```bash +# Get Gateway address +GATEWAY_LB=$(kubectl get gateway -n upbound-system spaces -o jsonpath='{.status.addresses[0].value}') + +# Test connectivity using --connect-to to route to the new Gateway +curl --connect-to "${SPACES_ROUTER_HOST}:443:${GATEWAY_LB}:443" "https://${SPACES_ROUTER_HOST}/version" +# Expected: 401 Unauthorized (routing works, auth required) +``` + +**7. Update your DNS record to point to the new Gateway address** + +**8. Update your `values.yaml` to disable Ingress, then upgrade Spaces:** + +```yaml +ingress: + provision: false +``` + +```bash +helm upgrade spaces oci://xpkg.upbound.io/spaces-artifacts/spaces \ + --version ${SPACES_VERSION} \ + --namespace upbound-system \ + -f values.yaml \ + --wait +``` + +**9. Uninstall ingress-nginx** + +```bash +helm uninstall ingress-nginx --namespace ingress-nginx +``` + +### Alternative ingress controller + +Use any Ingress controller that supports TLS passthrough. + +Configure your Ingress controller's Service with NLB +annotations. See [Cloud-specific annotations][expose-annotate]. + +**1. Install your chosen Ingress controller** + +**2. Update the ingress configuration in your `values.yaml`** + +```yaml +ingress: + provision: true + host: proxy.example.com + ingressClassName: + annotations: + # Add your controller's TLS passthrough annotations + podLabels: + # Labels matching your controller's pods + namespaceLabels: + # Labels matching your controller's namespace +``` + +**3. Upgrade Spaces** + +```bash +helm upgrade spaces oci://xpkg.upbound.io/spaces-artifacts/spaces \ + --version ${SPACES_VERSION} \ + --namespace upbound-system \ + -f values.yaml \ + --wait +``` + +**4. Get the new load balancer address and update DNS** + +```bash +kubectl get svc -n -o jsonpath='{.status.loadBalancer.ingress[0].hostname}' +``` + +**5. Uninstall ingress-nginx** + +```bash +helm uninstall ingress-nginx --namespace ingress-nginx +``` + + +## Can't upgrade to Spaces 1.16 before March 2026 + + +Choose your migration option: + +| Option | When to use | +|--------|-------------| +| [Gateway API](#gateway-api-spaces-110) | Already using Gateway API or need shared gateway | +| [Traefik](#traefik-or-alternative-ingress-controller) | Migrate from nginx Ingress to alternative controller | + +Export your current Helm values to a file (or use your existing values file if +stored in Git): + +```bash +helm get values spaces -n upbound-system -o yaml > values.yaml +``` + + +### Gateway API (Spaces 1.10+) + + +Gateway API support has been available since Spaces 1.10. See [Gateway API +Configuration][gateway-api-config] for detailed setup instructions. + +:::note +Pre-1.16 Spaces doesn't support running Ingress and Gateway API +simultaneously. This migration requires switching over in a single upgrade, +which causes brief downtime during DNS propagation. +::: + +**Remove existing ingress resources** Delete the Ingress resource and ingress-nginx controller: @@ -36,9 +441,11 @@ This step forces downtime for API access through spaces-router until the Gateway API configuration is complete. ::: -### 2. Install a Gateway API controller +**Install a gateway API controller** + +Install a Gateway API implementation that supports TLS passthrough and +`TLSRoute`. -Install a Gateway API implementation that supports TLS passthrough and `TLSRoute`. The following example uses Envoy Gateway: ```bash @@ -50,9 +457,9 @@ helm -n envoy-gateway-system upgrade --install --wait --wait-for-jobs \ --version "${ENVOY_GATEWAY_VERSION}" ``` -### 3. Create GatewayClass resource +**Create GatewayClass resource** -Create a `GatewayClass` resource appropriate for your cloud provider. +Create a `GatewayClass` resource appropriate for your cloud provider. @@ -76,7 +483,6 @@ EOF - ```bash kubectl apply -f - --server-side < - -### 4. Create Gateway resource +**Create Gateway resource** Create a Gateway resource in the `upbound-system` namespace. @@ -140,7 +545,6 @@ EOF - ```bash @@ -166,9 +570,6 @@ EOF - - - ```bash @@ -194,8 +595,6 @@ EOF - - :::note During installation or upgrade, you can use the Spaces Helm chart to create the Gateway automatically with these parameters: @@ -203,8 +602,7 @@ Gateway automatically with these parameters: - `gatewayAPI.gateway.className=spaces` ::: - -### 5. Get the load balancer hostname +**Get the load balancer hostname** Check the externally routable hostname for the Gateway's load balancer. The Helm `gatewayAPI.host` parameter requires this hostname. @@ -217,7 +615,7 @@ kubectl get service -n envoy-gateway-system \ -o jsonpath='{.items[0].status.loadBalancer.ingress[0].hostname}' ``` -### 6. Upgrade the Spaces Helm release +**Upgrade the Spaces Helm release** Upgrade the Spaces installation with Gateway API parameters: @@ -232,22 +630,149 @@ helm -n upbound-system upgrade spaces \ --wait ``` -### 7. Restart spaces-router (Optional) +**Restart spaces-router (optional)** If the `gatewayAPI.host` value differs from the previous `ingress.host` value, -restart the spaces-router pod to regenerate the certificate with the correct SAN -(Subject Alternative Name): +restart the spaces-router pod to regenerate the certificate with the correct +SAN: ```bash kubectl -n upbound-system rollout restart deployment spaces-router kubectl -n upbound-system rollout status deployment spaces-router ``` -## Additional resources +**Configure values.yaml** + +Update your `values.yaml` to disable Ingress and enable Gateway API: + +```yaml +ingress: + provision: false + +gatewayAPI: + host: proxy.example.com # Must match your current ingress.host + gateway: + provision: true + name: spaces + className: spaces # Must match your GatewayClass name + spacesRouterRoute: + provision: true + # Labels for NetworkPolicy - must match your gateway controller's pods + podLabels: + app.kubernetes.io/name: envoy + app.kubernetes.io/component: proxy + app.kubernetes.io/managed-by: envoy-gateway + namespaceLabels: + kubernetes.io/metadata.name: envoy-gateway-system +``` + +**Upgrade Spaces** + +This disables Ingress and enables Gateway API: + +```bash +helm upgrade spaces oci://xpkg.upbound.io/spaces-artifacts/spaces \ + --version ${SPACES_VERSION} \ + --namespace upbound-system \ + -f values.yaml \ + --wait +``` + +**Get the gateway address and update DNS** + +```bash +kubectl get gateway -n upbound-system spaces -o jsonpath='{.status.addresses[0].value}' +``` + +Update your DNS record to this address. + +**Verify connectivity** + +```bash +curl -v "https://${SPACES_ROUTER_HOST}/version" +# Expected: 401 Unauthorized (routing works, auth required) +``` + +**Uninstall ingress-nginx** + +```bash +helm uninstall ingress-nginx --namespace ingress-nginx +``` + +### Traefik (or alternative ingress controller) -- [Spaces Deployment] -- [Kubernetes Announcement] +Traefik can pick up the existing nginx Ingress via +`--providers.kubernetesIngressNGINX`. See the [Traefik migration +guide][traefik-migrate] for details. + +**1. Install Traefik with nginx Ingress provider** + +```bash +helm repo add traefik https://traefik.github.io/charts +helm repo update +helm upgrade --install traefik traefik/traefik \ + --create-namespace --namespace traefik \ + --set 'service.type=LoadBalancer' \ + --set 'additionalArguments={--providers.kubernetesIngressNGINX}' \ + --wait +``` + +Configure Traefik's Service with NLB annotations. See +[Cloud-specific annotations][expose-annotate]. + +**2. Validate before switching DNS** + +```bash +# Get Traefik load balancer address +TRAEFIK_LB=$(kubectl get svc -n traefik traefik -o jsonpath='{.status.loadBalancer.ingress[0].hostname}') + +# Test connectivity using --connect-to to route to Traefik +curl --connect-to "${SPACES_ROUTER_HOST}:443:${TRAEFIK_LB}:443" "https://${SPACES_ROUTER_HOST}/version" +# Expected: 401 Unauthorized (routing works, auth required) +``` + +**3. Update DNS to point to Traefik** + +```bash +kubectl get svc -n traefik traefik -o jsonpath='{.status.loadBalancer.ingress[0].hostname}' +``` + +Update your DNS record to this address. For gradual migration, use weighted DNS routing. + +**4. Preserve the nginx IngressClass before uninstalling ingress-nginx** + +```bash +helm upgrade ingress-nginx ingress-nginx \ + --repo https://kubernetes.github.io/ingress-nginx \ + --namespace ingress-nginx \ + --reuse-values \ + --set-json 'controller.ingressClassResource.annotations={"helm.sh/resource-policy": "keep"}' +``` + +**5. Uninstall ingress-nginx** + +```bash +helm uninstall ingress-nginx --namespace ingress-nginx +``` + +Keep `ingress.provision: true` so the Spaces chart continues to manage the +Ingress resource. Traefik picks it up via the nginx provider. + + +## Verification + +After migration, verify connectivity: + +```bash +curl -v "https://${SPACES_ROUTER_HOST}/version" +# Expected: 401 Unauthorized +``` -[spaces deployment]: -/manuals/spaces/howtos/self-hosted/self-hosted-spaces-deployment -[kubernetes announcement]: https://www.kubernetes.dev/blog/2025/11/12/ingress-nginx-retirement/ +[envoy-install]: https://gateway.envoyproxy.io/docs/install/ +[spaces-install]: /manuals/spaces/howtos/self-hosted/self-hosted-spaces-deployment/ +[traefik-migrate]: https://doc.traefik.io/traefik/migrate/nginx-to-traefik/ +[spaces-deploy]: /manuals/spaces/howtos/self-hosted/self-hosted-spaces-deployment/ +[k8s-announce]: https://www.kubernetes.dev/blog/2025/11/12/ingress-nginx-retirement/ +[expose]: /manuals/spaces/howtos/self-hosted/ingress/ +[expose-annotate]: /manuals/spaces/howtos/self-hosted/ingress/#cloud-specific-annotations +[gateway-api]: https://gateway-api.sigs.k8s.io/ diff --git a/docs/manuals/spaces/howtos/self-hosted/ingress.md b/docs/manuals/spaces/howtos/self-hosted/ingress.md new file mode 100644 index 000000000..9dc06b140 --- /dev/null +++ b/docs/manuals/spaces/howtos/self-hosted/ingress.md @@ -0,0 +1,134 @@ +--- +title: Exposing Spaces externally +sidebar_position: 5 +description: Options for exposing Spaces externally +--- + +import { CodeBlock } from '@site/src/components/GlobalLanguageSelector'; + + +You can expose Spaces externally using of three options: + +| Option | When to use | +|--------|-------------| +| LoadBalancer Service | Simplest setup, recommended for most deployments | +| Gateway API | Organization already using Gateway API, or need shared gateway across services | +| Ingress | Organization already using Ingress, or need shared load balancer across services | + +## LoadBalancer Service + +Upbound recommends a LoadBalancer Service to expose `spaces-router`. + + +:::important +Use a Network Load Balancer (L4), not an Application Load Balancer (L7). Spaces +uses long-lived connections for watch traffic that L7 load balancers may +timeout. +::: + +### Configuration + +```yaml +externalTLS: + host: proxy.example.com # Externally routable hostname for TLS certificates + +router: + proxy: + service: + type: LoadBalancer + annotations: + # AWS NLB (see Cloud-Specific Annotations for other clouds) + service.beta.kubernetes.io/aws-load-balancer-type: external + service.beta.kubernetes.io/aws-load-balancer-scheme: internet-facing + service.beta.kubernetes.io/aws-load-balancer-nlb-target-type: ip +``` + +See [Cloud-Specific Annotations](#cloud-specific-annotations) for GCP and Azure. + + +### Get the LoadBalancer address + + +After installation: + +```bash +kubectl get svc -n upbound-system spaces-router \ + -o jsonpath='{.status.loadBalancer.ingress[0].hostname}' +``` + +Create or update a DNS record pointing your `externalTLS.host` to this address. + +## Ingress + +Use Ingress if you need to share a load balancer across multiple services or +have specific networking requirements. + +### Requirements + +- TLS passthrough support in your Ingress controller +- Network Load Balancer (L4) strongly recommended for long-lived connections + +Configure your Ingress controller's Service with [NLB annotations](#cloud-specific-annotations). + +### Configuration + +```yaml +ingress: + provision: true + host: proxy.example.com + ingressClassName: "" + # Annotations to add to the Ingress resource + annotations: {} + # Pod labels of the Ingress controller - used for network policy + podLabels: {} + # Namespace labels of the Ingress controller - used for network policy + namespaceLabels: {} +``` + +### Traefik (with nginx provider) + +Traefik can use the [kubernetesIngressNGINX provider][traefik-provider] to +handle nginx-style Ingress resources with TLS passthrough. + +```yaml +ingress: + provision: true + host: proxy.example.com + ingressClassName: nginx + annotations: + nginx.ingress.kubernetes.io/ssl-passthrough: "true" + nginx.ingress.kubernetes.io/force-ssl-redirect: "true" + podLabels: + app.kubernetes.io/name: traefik + namespaceLabels: + kubernetes.io/metadata.name: traefik +``` + +## Gateway API + +Spaces supports the [Gateway API][gateway-api-docs]. Use this option if your +organization is already using Gateway API or needs a shared gateway across +multiple services. + +### Requirements + +- A Gateway API controller (for example, Envoy Gateway, Cilium, or Traefik) +- Gateway API CRDs installed in your cluster +- TLS passthrough support +- Network Load Balancer (L4) strongly recommended + +## Cloud-specific annotations + +Network Load Balancers (L4) are strongly recommended. Spaces uses long-lived +watch connections (hours or days) for kubectl and ArgoCD. L7 load balancers may +timeout these connections. Use these annotations on the LoadBalancer Service +(spaces-router, Ingress controller, or Gateway). + +| Cloud | Annotations | +|-------|-------------| +| **AWS** | `service.beta.kubernetes.io/aws-load-balancer-type: external`
`service.beta.kubernetes.io/aws-load-balancer-scheme: internet-facing`
`service.beta.kubernetes.io/aws-load-balancer-nlb-target-type: ip` | +| **GCP** | `cloud.google.com/l4-rbs: enabled` | +| **Azure** | None required (L4 by default) | + +[traefik-provider]: https://doc.traefik.io/traefik/reference/install-configuration/providers/kubernetes/kubernetes-ingress-nginx/ +[gateway-api-docs]: https://gateway-api.sigs.k8s.io/ diff --git a/utils/vale/styles/Upbound/spelling-exceptions.txt b/utils/vale/styles/Upbound/spelling-exceptions.txt index 80f6e139c..5c8783576 100644 --- a/utils/vale/styles/Upbound/spelling-exceptions.txt +++ b/utils/vale/styles/Upbound/spelling-exceptions.txt @@ -144,4 +144,12 @@ XRDs XRs Zendesk Upjet +GCP +nginx +Traefik +Traefik's +hostname +HTTPRoute +TLSRoute +passthrough From d4a5498a86115d38ee72812b19eba8697a12186c Mon Sep 17 00:00:00 2001 From: Rae Sharp Date: Tue, 27 Jan 2026 18:16:14 -0500 Subject: [PATCH 04/10] vale --- docs/manuals/spaces/howtos/self-hosted/ingress.md | 9 ++++++--- .../howtos/self-hosted/self-hosted-spaces-deployment.md | 7 +++++-- 2 files changed, 11 insertions(+), 5 deletions(-) diff --git a/docs/manuals/spaces/howtos/self-hosted/ingress.md b/docs/manuals/spaces/howtos/self-hosted/ingress.md index 9dc06b140..44b47a773 100644 --- a/docs/manuals/spaces/howtos/self-hosted/ingress.md +++ b/docs/manuals/spaces/howtos/self-hosted/ingress.md @@ -14,8 +14,9 @@ You can expose Spaces externally using of three options: | LoadBalancer Service | Simplest setup, recommended for most deployments | | Gateway API | Organization already using Gateway API, or need shared gateway across services | | Ingress | Organization already using Ingress, or need shared load balancer across services | - + ## LoadBalancer Service + Upbound recommends a LoadBalancer Service to expose `spaces-router`. @@ -27,7 +28,7 @@ timeout. ::: ### Configuration - + ```yaml externalTLS: host: proxy.example.com # Externally routable hostname for TLS certificates @@ -67,8 +68,9 @@ have specific networking requirements. - TLS passthrough support in your Ingress controller - Network Load Balancer (L4) strongly recommended for long-lived connections - + Configure your Ingress controller's Service with [NLB annotations](#cloud-specific-annotations). + ### Configuration @@ -129,6 +131,7 @@ timeout these connections. Use these annotations on the LoadBalancer Service | **AWS** | `service.beta.kubernetes.io/aws-load-balancer-type: external`
`service.beta.kubernetes.io/aws-load-balancer-scheme: internet-facing`
`service.beta.kubernetes.io/aws-load-balancer-nlb-target-type: ip` | | **GCP** | `cloud.google.com/l4-rbs: enabled` | | **Azure** | None required (L4 by default) | + [traefik-provider]: https://doc.traefik.io/traefik/reference/install-configuration/providers/kubernetes/kubernetes-ingress-nginx/ [gateway-api-docs]: https://gateway-api.sigs.k8s.io/ diff --git a/docs/manuals/spaces/howtos/self-hosted/self-hosted-spaces-deployment.md b/docs/manuals/spaces/howtos/self-hosted/self-hosted-spaces-deployment.md index 230aa2411..c844a4b14 100644 --- a/docs/manuals/spaces/howtos/self-hosted/self-hosted-spaces-deployment.md +++ b/docs/manuals/spaces/howtos/self-hosted/self-hosted-spaces-deployment.md @@ -513,8 +513,10 @@ kubectl wait controlplane ctp1 --for condition=Ready=True --timeout=360s ``` ## Connect to your control plane - -Connect to your control plane with the `up ctx` command. With your kubeconfig still pointed at the Kubernetes cluster where you installed the Upbound Space, run the following: + +Connect to your control plane with the `up ctx` command. With your kubeconfig +still pointed at the Kubernetes cluster where you installed the Upbound Space, +run the following: ```bash up ctx ./default/ctp1 @@ -535,6 +537,7 @@ up ctx - :::tip Learn how to use the up CLI to navigate around Upbound by reading the [up ctx command reference][up-ctx-command-reference]. ::: + [up-ctx-command-reference]: /reference/cli-reference [contact-upbound]: https://www.upbound.io/contact-us From 3fe664cc0a5b4119960497898729d6c25d667c24 Mon Sep 17 00:00:00 2001 From: Rae Sharp Date: Tue, 27 Jan 2026 18:19:16 -0500 Subject: [PATCH 05/10] vale again --- .../spaces/howtos/self-hosted/ingress-nginx-migration.md | 5 ++++- .../howtos/self-hosted/self-hosted-spaces-deployment.md | 4 ++-- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/manuals/spaces/howtos/self-hosted/ingress-nginx-migration.md b/docs/manuals/spaces/howtos/self-hosted/ingress-nginx-migration.md index 7088ad2d3..908e9d644 100644 --- a/docs/manuals/spaces/howtos/self-hosted/ingress-nginx-migration.md +++ b/docs/manuals/spaces/howtos/self-hosted/ingress-nginx-migration.md @@ -354,8 +354,10 @@ helm uninstall ingress-nginx --namespace ingress-nginx Use any Ingress controller that supports TLS passthrough. + Configure your Ingress controller's Service with NLB annotations. See [Cloud-specific annotations][expose-annotate]. + **1. Install your chosen Ingress controller** @@ -716,9 +718,10 @@ helm upgrade --install traefik traefik/traefik \ --set 'additionalArguments={--providers.kubernetesIngressNGINX}' \ --wait ``` - + Configure Traefik's Service with NLB annotations. See [Cloud-specific annotations][expose-annotate]. + **2. Validate before switching DNS** diff --git a/docs/manuals/spaces/howtos/self-hosted/self-hosted-spaces-deployment.md b/docs/manuals/spaces/howtos/self-hosted/self-hosted-spaces-deployment.md index c844a4b14..0db08e63a 100644 --- a/docs/manuals/spaces/howtos/self-hosted/self-hosted-spaces-deployment.md +++ b/docs/manuals/spaces/howtos/self-hosted/self-hosted-spaces-deployment.md @@ -513,10 +513,11 @@ kubectl wait controlplane ctp1 --for condition=Ready=True --timeout=360s ``` ## Connect to your control plane - + Connect to your control plane with the `up ctx` command. With your kubeconfig still pointed at the Kubernetes cluster where you installed the Upbound Space, run the following: + ```bash up ctx ./default/ctp1 @@ -537,7 +538,6 @@ up ctx - :::tip Learn how to use the up CLI to navigate around Upbound by reading the [up ctx command reference][up-ctx-command-reference]. ::: - [up-ctx-command-reference]: /reference/cli-reference [contact-upbound]: https://www.upbound.io/contact-us From 2f6cd6c7778ad5d24be6c5a74876943355ab69e2 Mon Sep 17 00:00:00 2001 From: Rae Sharp Date: Tue, 27 Jan 2026 18:21:48 -0500 Subject: [PATCH 06/10] x --- .../howtos/self-hosted/self-hosted-spaces-deployment.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/manuals/spaces/howtos/self-hosted/self-hosted-spaces-deployment.md b/docs/manuals/spaces/howtos/self-hosted/self-hosted-spaces-deployment.md index 0db08e63a..e24b95ab8 100644 --- a/docs/manuals/spaces/howtos/self-hosted/self-hosted-spaces-deployment.md +++ b/docs/manuals/spaces/howtos/self-hosted/self-hosted-spaces-deployment.md @@ -513,12 +513,14 @@ kubectl wait controlplane ctp1 --for condition=Ready=True --timeout=360s ``` ## Connect to your control plane + -Connect to your control plane with the `up ctx` command. With your kubeconfig +Connect to your control plane with the up ctx command. With your kubeconfig still pointed at the Kubernetes cluster where you installed the Upbound Space, run the following: + ```bash up ctx ./default/ctp1 ``` From b6c5c24853b92ad0aa0c4283a602252ae986221c Mon Sep 17 00:00:00 2001 From: Rae Sharp Date: Tue, 27 Jan 2026 18:24:08 -0500 Subject: [PATCH 07/10] ctx exception --- utils/vale/styles/Upbound/spelling-exceptions.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/utils/vale/styles/Upbound/spelling-exceptions.txt b/utils/vale/styles/Upbound/spelling-exceptions.txt index 5c8783576..ec6468956 100644 --- a/utils/vale/styles/Upbound/spelling-exceptions.txt +++ b/utils/vale/styles/Upbound/spelling-exceptions.txt @@ -37,6 +37,7 @@ configmaps CRDs Crossplane Crossplane's +ctx Datadog declaratively downscaling From dc137faf5e15e5e84fe21456390a97c3e78639f7 Mon Sep 17 00:00:00 2001 From: Rae Sharp Date: Thu, 29 Jan 2026 15:03:45 -0500 Subject: [PATCH 08/10] commit reorder --- .../self-hosted/ingress-nginx-migration.md | 173 +++--------------- 1 file changed, 30 insertions(+), 143 deletions(-) diff --git a/docs/manuals/spaces/howtos/self-hosted/ingress-nginx-migration.md b/docs/manuals/spaces/howtos/self-hosted/ingress-nginx-migration.md index 908e9d644..34939152a 100644 --- a/docs/manuals/spaces/howtos/self-hosted/ingress-nginx-migration.md +++ b/docs/manuals/spaces/howtos/self-hosted/ingress-nginx-migration.md @@ -14,11 +14,13 @@ guide covers migration options for existing Spaces deployments. For help choosing an exposure method, see [Exposing Spaces Externally][expose]. + ## Prerequisites @@ -52,6 +54,9 @@ Choose your migration option: All paths follow the same process: upgrade to 1.16+, switch exposure method, then uninstall ingress-nginx. + + + -## Can't upgrade to Spaces 1.16 before March 2026 +## Migrate current Spaces version before March 2026 Choose your migration option: @@ -451,7 +414,7 @@ Install a Gateway API implementation that supports TLS passthrough and The following example uses Envoy Gateway: ```bash -export ENVOY_GATEWAY_VERSION=v1.2.4 +export ENVOY_GATEWAY_VERSION= # Example: v1.2.4 helm -n envoy-gateway-system upgrade --install --wait --wait-for-jobs \ --timeout 300s --create-namespace envoy-gateway \ @@ -461,29 +424,8 @@ helm -n envoy-gateway-system upgrade --install --wait --wait-for-jobs \ **Create GatewayClass resource** -Create a `GatewayClass` resource appropriate for your cloud provider. - - - -```bash -kubectl apply -f - --server-side < +Create a `GatewayClass` resource. - ```bash kubectl apply -f - --server-side < - - - -```bash -kubectl apply -f - --server-side < - **Create Gateway resource** Create a Gateway resource in the `upbound-system` namespace. - - -```bash -kubectl apply -f - --server-side < - - ```bash kubectl apply -f - --server-side < +**Update your Helm values** - +```yaml +ingress: + provision: false -```bash -kubectl apply -f - --server-side < - -:::note -During installation or upgrade, you can use the Spaces Helm chart to create the -Gateway automatically with these parameters: -- `gatewayAPI.gateway.provision=true` -- `gatewayAPI.gateway.className=spaces` -::: - **Get the load balancer hostname** Check the externally routable hostname for the Gateway's load balancer. @@ -779,3 +665,4 @@ curl -v "https://${SPACES_ROUTER_HOST}/version" [expose]: /manuals/spaces/howtos/self-hosted/ingress/ [expose-annotate]: /manuals/spaces/howtos/self-hosted/ingress/#cloud-specific-annotations [gateway-api]: https://gateway-api.sigs.k8s.io/ +[gateway-api-config]: /manuals/spaces/howtos/self-hosted/ingress/#gateway-api From 9b4c4ff6bdefd8e435992d12a7ca2d06a5181608 Mon Sep 17 00:00:00 2001 From: Rae Sharp Date: Thu, 29 Jan 2026 15:16:32 -0500 Subject: [PATCH 09/10] commenting out v1.16 refs --- .../howtos/self-hosted/ingress-nginx-migration.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/manuals/spaces/howtos/self-hosted/ingress-nginx-migration.md b/docs/manuals/spaces/howtos/self-hosted/ingress-nginx-migration.md index 34939152a..9926f917b 100644 --- a/docs/manuals/spaces/howtos/self-hosted/ingress-nginx-migration.md +++ b/docs/manuals/spaces/howtos/self-hosted/ingress-nginx-migration.md @@ -13,17 +13,16 @@ import GlobalLanguageSelector, { CodeBlock } from '@site/src/components/GlobalLa guide covers migration options for existing Spaces deployments. For help choosing an exposure method, see [Exposing Spaces Externally][expose]. - - +version--> ## Prerequisites + Set environment variables used throughout this guide: @@ -41,6 +40,7 @@ helm get values spaces -n upbound-system -o yaml > values.yaml You'll merge new configuration into this file throughout the migration. + -Configure your Ingress controller's Service with NLB +Configure your Ingress controller's Service with `NLB` annotations. See [Cloud-specific annotations][expose-annotate]. - **1. Install your chosen Ingress controller** @@ -361,6 +358,8 @@ kubectl get svc -n -o jsonpath='{.st helm uninstall ingress-nginx --namespace ingress-nginx ``` + +version--> ## Migrate current Spaces version before March 2026 From a194fcb4b50a647d9c9eee6db0cf013211610902 Mon Sep 17 00:00:00 2001 From: Rae Sharp Date: Thu, 29 Jan 2026 15:20:52 -0500 Subject: [PATCH 10/10] step numbering consistency --- .../self-hosted/ingress-nginx-migration.md | 26 +++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/manuals/spaces/howtos/self-hosted/ingress-nginx-migration.md b/docs/manuals/spaces/howtos/self-hosted/ingress-nginx-migration.md index 9926f917b..34ecfaa4f 100644 --- a/docs/manuals/spaces/howtos/self-hosted/ingress-nginx-migration.md +++ b/docs/manuals/spaces/howtos/self-hosted/ingress-nginx-migration.md @@ -391,7 +391,7 @@ simultaneously. This migration requires switching over in a single upgrade, which causes brief downtime during DNS propagation. ::: -**Remove existing ingress resources** +**1. Remove existing ingress resources** Delete the Ingress resource and ingress-nginx controller: @@ -405,7 +405,7 @@ This step forces downtime for API access through spaces-router until the Gateway API configuration is complete. ::: -**Install a gateway API controller** +**2. Install a gateway API controller** Install a Gateway API implementation that supports TLS passthrough and `TLSRoute`. @@ -421,7 +421,7 @@ helm -n envoy-gateway-system upgrade --install --wait --wait-for-jobs \ --version "${ENVOY_GATEWAY_VERSION}" ``` -**Create GatewayClass resource** +**3. Create GatewayClass resource** Create a `GatewayClass` resource. @@ -441,7 +441,7 @@ spec: namespace: envoy-gateway-system EOF ``` -**Create Gateway resource** +**4. Create Gateway resource** Create a Gateway resource in the `upbound-system` namespace. @@ -467,7 +467,7 @@ spec: EOF ``` -**Update your Helm values** +**5. Update your Helm values** ```yaml ingress: @@ -489,7 +489,7 @@ gatewayAPI: namespaceLabels: kubernetes.io/metadata.name: envoy-gateway-system ``` -**Get the load balancer hostname** +**6. Get the load balancer hostname** Check the externally routable hostname for the Gateway's load balancer. The Helm `gatewayAPI.host` parameter requires this hostname. @@ -502,7 +502,7 @@ kubectl get service -n envoy-gateway-system \ -o jsonpath='{.items[0].status.loadBalancer.ingress[0].hostname}' ``` -**Upgrade the Spaces Helm release** +**7. Upgrade the Spaces Helm release** Upgrade the Spaces installation with Gateway API parameters: @@ -517,7 +517,7 @@ helm -n upbound-system upgrade spaces \ --wait ``` -**Restart spaces-router (optional)** +**8. Restart spaces-router (optional)** If the `gatewayAPI.host` value differs from the previous `ingress.host` value, restart the spaces-router pod to regenerate the certificate with the correct @@ -528,7 +528,7 @@ kubectl -n upbound-system rollout restart deployment spaces-router kubectl -n upbound-system rollout status deployment spaces-router ``` -**Configure values.yaml** +**9. Configure values.yaml** Update your `values.yaml` to disable Ingress and enable Gateway API: @@ -553,7 +553,7 @@ gatewayAPI: kubernetes.io/metadata.name: envoy-gateway-system ``` -**Upgrade Spaces** +**10. Upgrade Spaces** This disables Ingress and enables Gateway API: @@ -565,7 +565,7 @@ helm upgrade spaces oci://xpkg.upbound.io/spaces-artifacts/spaces \ --wait ``` -**Get the gateway address and update DNS** +**11. Get the gateway address and update DNS** ```bash kubectl get gateway -n upbound-system spaces -o jsonpath='{.status.addresses[0].value}' @@ -573,14 +573,14 @@ kubectl get gateway -n upbound-system spaces -o jsonpath='{.status.addresses[0]. Update your DNS record to this address. -**Verify connectivity** +**12. Verify connectivity** ```bash curl -v "https://${SPACES_ROUTER_HOST}/version" # Expected: 401 Unauthorized (routing works, auth required) ``` -**Uninstall ingress-nginx** +**13. Uninstall ingress-nginx** ```bash helm uninstall ingress-nginx --namespace ingress-nginx