[lakshmimsft]

Summary

Restore k3d cluster preparation guidance on /installation/, with links from the control-plane installation page and getting-started guide. Document disabling Traefik, retaining servicelb, mapping a localhost HTTP port, and using the route's hostname when accessing an application.

Reason for change

The installation-docs restructure removed the old k3d setup instructions. A default k3d cluster includes Traefik, which can conflict with Radius's default Contour installation through ingress ports and Gateway API CRD ownership.

The old command also disabled servicelb. Restoring it verbatim would be incorrect: the previous Bitnami Contour chart exposed Envoy through host ports, while the current Contour chart defaults to a Kubernetes LoadBalancer Service. The documented setup leaves servicelb enabled so traffic forwarded by k3d can reach Envoy.

Related: radius-project/radius#13547. The Contour chart migration is documented in radius-project/radius#10573.

How to test

1. Follow docs/README.md to install the Node.js dependencies. From docs/, run:

   npm run build -- --cacheDir "$PWD/node_modules/.cache/hugo"

   Expected: the site builds successfully. Open /installation/ in a local preview and check the new Prepare a k3d cluster section. Follow the links to it from /installation/control-plane/ and /getting-started/install-radius/, and check both links to the Routes integration guide.

2. With a recent k3d release, a supported Kubernetes image, a compatible kubectl, the Radius CLI, and Docker with at least 8 GB allocated, create a new cluster using the documented options. Use an unused cluster name and local port. Run rad install kubernetes in that cluster's context. Expected: Radius installs Contour and creates the radius gateway, without Traefik CRD ownership errors.

3. In the test cluster, create a backend and an HTTP route. These commands assume the documented localhost port, 18081:

   kubectl create deployment port-test --image=nginx:alpine
   kubectl expose deployment port-test --port=80
   kubectl rollout status deployment/port-test --timeout=120s
   kubectl apply -f - <<'YAML'
   apiVersion: gateway.networking.k8s.io/v1
   kind: HTTPRoute
   metadata:
     name: port-test
   spec:
     parentRefs:
       - name: radius
         namespace: radius-system
         sectionName: http
     hostnames:
       - frontend.example.com
     rules:
       - backendRefs:
           - name: port-test
             port: 80
   YAML
   kubectl wait --for=condition=Programmed gateway/radius \
     -n radius-system --timeout=120s
   curl --fail --retry 5 --retry-delay 3 \
     -H "Host: frontend.example.com" http://localhost:18081/
   curl -sS -o /dev/null -w '%{http_code}\n' \
     -H "Host: unmatched.example.com" http://localhost:18081/

   Expected: the matching hostname returns HTTP 200 and the nginx welcome page; the unmatched hostname returns HTTP 404. The svclb-contour-envoy-* pod in kube-system is running and the contour-envoy Service in radius-system has an external address. This tests the ingress network path with a Kubernetes HTTPRoute, not a Radius application deployment.

Validation performed:

• npm run build -- --cacheDir "$PWD/node_modules/.cache/hugo" (from docs/): passed, with an existing Docsy deprecation warning. The unqualified build initially failed because of local Go/Hugo tooling and then a PostCSS permission error with the external Hugo cache; installing the pinned dependencies and using a project-local cache resolved those failures without repository configuration changes.
• npx --no-install cspell --config .github/linters/.cspell.yml --no-progress docs/content/installation/_index.md docs/content/installation/control-plane/_index.md docs/content/getting-started/install-radius/_index.md (repository root): passed, zero spelling issues.
• git diff --check: passed.
• Parsed the generated HTML: passed for the k3d command, the new section anchor, both incoming links, and both Routes integration link targets.
• Runtime verification used k3d 5.9.0, k3s 1.32.9, and Radius 0.62.0, with Traefik disabled and servicelb enabled. Initial API timeouts required freeing local resources, completing CRD establishment, and retrying the installation; this was not a clean first-attempt installation test. The final Radius control plane, Contour, and Envoy pods were ready.
• curl --noproxy '*' -fSs --max-time 10 -o /dev/null -w 'Matching hostname: HTTP %{http_code}\n' -H 'Host: docs-port-test.localhost' http://127.0.0.1:18081/: passed, HTTP 200 through Radius-installed Contour to the test backend.
• curl --noproxy '*' -sS --max-time 10 -o /dev/null -w 'Unmatched hostname: HTTP %{http_code}\n' -H 'Host: unmatched.localhost' http://127.0.0.1:18081/: passed, HTTP 404.

The runtime check validates HTTP port mapping, not TLS, Radius application deployment, or the supported Kubernetes version matrix. The docs therefore refer to the current system requirements rather than pinning the test's Kubernetes version.

File change summary

File	Summary of change
docs/content/installation/_index.md	Add k3d cluster creation, Traefik and servicelb guidance, existing-cluster precautions, and hostname-aware HTTP access.
docs/content/installation/control-plane/_index.md	Link to k3d prerequisites before the installation commands.
docs/content/getting-started/install-radius/_index.md	Link to k3d preparation from the prerequisites.

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None