docs: fix install-blocking commands in the v1.1 k3d guide and document the websocket policy

[Ketharan]

Purpose

Found by installing OpenChoreo v1.1.6 on a clean k3d cluster following only this guide, applying nothing from outside it. Two of the guide's own commands abort the install, and a third gap leaves occ component exec silently broken.

Approach

1. kubectl wait on a secret that does not exist yet (3 occurrences)

Each plane's registration step waits for the agent secret:

kubectl wait -n openchoreo-data-plane \
  --for=jsonpath='{.data.ca\.crt}' secret/cluster-agent-tls --timeout=120s

kubectl wait fails immediately with NotFound when the resource does not exist — it does not wait for it to appear. Immediately after the plane install, cert-manager has not yet produced the secret, so the install aborts:

Error from server (NotFound): secrets "cluster-agent-tls" not found

Reproduced on two independent clean installs. The secret appeared ~25s later, so this is purely a race the command cannot survive.

Changed to wait on the Certificate, which exists as soon as the chart is applied — the pattern the v1.2 guide already uses:

kubectl wait -n openchoreo-data-plane \
  --for=condition=Ready certificate/cluster-agent-dataplane-tls --timeout=120s

Applied for all three planes, using each plane's actual certificate name (cluster-agent-dataplane-tls, cluster-agent-workflowplane-tls, cluster-agent-observabilityplane-tls).

2. Logs module install has no --timeout

Its post-install opensearch-setup-logs job blocks until OpenSearch is ready, which took 5m48s here — past Helm's default 5m, so the install failed. The observability plane core install already passes --timeout 25m; the logs module was left on the default. Added --timeout 15m.

3. WebSocket upgrades are not documented

occ component exec opens a WebSocket through the control plane gateway, and kgateway rejects upgrades unless the listener allows them. The required HTTPListenerPolicy is not in the v1.1 chart and is not mentioned in this guide, so exec does not work after completing it. Verified on the doc-only install:

HTTPListenerPolicy in cluster:  No resources found
WebSocket upgrade attempt:      HTTP 403

Applying the policy changes that to 101 Switching Protocols.

Adds a short section at the end of Step 3 with the policy, plus a warning that the failure mode is misleading: the gateway returns 403 Forbidden before the request reaches the API server, so nothing appears in the openchoreo-api logs and it reads as a permissions problem. The note also states that exec requires component:exec, which the default developer and platform-engineer roles carry.

Related Issues

N/A

Checklist

• Tests added or updated (unit, integration, etc.)
• Samples updated (if applicable)
• This PR includes AI-generated code or content

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 8443b8a8-9dba-40cf-ba25-02dcec70394f

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}