docs: document the Kubernetes backend and its RBAC requirements

[oleksandr-nc]

This adds a ## Kubernetes Backend section between the Docker engine section and "Adapting ExApps to use HaRP".

• The HP_K8S_* variables, including how HaRP reaches and authenticates against the API server (HP_K8S_API_SERVER should be https, the token and its lifetime, HP_K8S_CA_FILE, HP_K8S_VERIFY_SSL), in-cluster versus out-of-cluster.
• RBAC permissions. A ready-to-apply Role and RoleBinding, the namespace and service account they assume, plus a table explaining what each verb is used for. The RoleBinding lives in the ExApp namespace and binds the service account of the HaRP pod, which usually lives in another namespace.
• NodePort and nodes. Why that one cluster-scoped permission exists and when it can be omitted: HaRP lists nodes whenever nodeport exposure is in use, also when an ExApp is enabled and after every restart, so a fixed --k8s_upstream_host does not remove the need for it. A ClusterRole and ClusterRoleBinding are included.
• Whether write access can be limited to deployment time. The recurring customer question, answered.
• Hardening the ExApp pods, since they run under the namespace default service account, and what that means for imagePullSecrets and the image pull policy (IfNotPresent, or Never for a local registry mapping since feat(k8s): accept image_pull_policy in the create payload #122).

The permission set

Derived by enumerating every _k8s_request() call site in haproxy_agent.py and its enclosing function, not from guesswork. It is complete for the current agent, including the /info reachability probe, which reads the discovery endpoint /api that every authenticated identity may read:

Resource	Verbs
apps/deployments	get, list, create, patch, delete
services	get, list, create, delete (create and delete are not used for manual exposure, get and list are)
persistentvolumeclaims	create, delete
pods	list
nodes (cluster-scoped)	list - only for nodeport exposure

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

📝 Walkthrough

Walkthrough

README.md clarifies which Kubernetes exposure types create a Service and describes API authentication settings. It specifies the namespaces for the Role and RoleBinding, and the conditions that require nodes:list. It also documents lifecycle permission use, registry credentials, and image pull policies.

Priority: ⬇️ Low

Merge Risk: 🟡 Moderate · up to 03024

Kubernetes deployments can expose credentials over HTTP or lose routing recovery after restart, while registry credentials may not apply to every Pod as documented.

Architecture Summary

Architecture risk: 🔵 Low · up to 03024

The change affects 1 system.

Changed systems: README.md

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

• observed — README.md (service) was modified; 1 changed file maps to changed impact.

Before / after behavior

• observed — Modified behavior in README.md: The resource-count description now says HaRP creates a Service for nodeport, clusterip, and loadbalancer exposure, but not for manual, which stores the upstream address in Deployment annotations.
• observed — Modified behavior in README.md: Replaces the brief in-cluster/out-of-cluster authentication description with API-server, bearer-token, CA-file, and SSL-verification settings and defaults. Clarifies that /info probes /api, which requires no additional permission.
• observed — Modified behavior in README.md: Clarifies that the Role’s namespace is the ExApp namespace and must match HP_K8S_NAMESPACE.
• observed — Modified behavior in README.md: Clarifies that the RoleBinding lives in the ExApp namespace while its subject identifies HaRP’s service account and that account’s namespace; mismatched subject details result in 403 responses.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly and concisely describes the main change: documenting the Kubernetes backend and its RBAC requirements.
Description check	✅ Passed	The description directly explains the Kubernetes documentation, authentication settings, RBAC permissions, NodePort behavior, and pod hardening covered by the changeset.

---

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.}

[coderabbitai]

Actionable comments posted: 4

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 10825994-43eb-4221-bddc-a149a230a36f

📥 Commits

Reviewing files that changed from the base of the PR and between 618751a and ec1947c.

📒 Files selected for processing (1)

• README.md

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

[coderabbitai]

Actionable comments posted: 2

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 9d6ae48e-8e2c-4eb6-8f13-dd78c8c5bf58

📥 Commits

Reviewing files that changed from the base of the PR and between ec1947c and 0302438.

📒 Files selected for processing (1)

• README.md

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.