Fix chart documentation defects found by following it

[richbg]

What this is

An audit followed this repo's documentation from scratch on a clean minikube cluster to install the chart. It worked in the end, but not by copy-paste. This PR fixes the mechanical, verified defects; findings that need a product or owner decision are listed at the bottom and deliberately not touched.

Every change was checked with helm template against chart 0.27.0. helm unittest gremlin passes 137 tests across 18 suites, and helm lint is clean.

Breaks an install

• No --create-namespace anywhere in the repo. All 13 namespaced helm install snippets pass --namespace gremlin and none creates it, so the first documented command fails on a clean cluster with Error: INSTALLATION FAILED: create: failed to create: namespaces "gremlin" not found. The string --create-namespace did not appear in the repo at all.
• Both uninstall commands failed. helm delete gremlin errors with release: not found (no --namespace), and helm delete --purge gremlin errors with unknown flag: --purge — Helm 2 syntax. Collapsed to one Helm 3 command, with a note that uninstall removes history by default and that the namespace is not deleted with the release.
• The "Example Usage" block did not run, and was broken three ways: --set split on the unescaped comma (Error: failed parsing --set data: key "kubernetes" has no value); the value k8s,kubernetes is not key=value so it yields no tags even once it parses; and it used gremlin.clusterID, an undocumented legacy alias for the gremlin.secret.clusterID this same README documents. Now --set 'gremlin.client.tags=env=prod\,team=core', verified to render GREMLIN_CLIENT_TAGS: env=prod,team=core.

Documented defaults that did not match the rendered manifest

Key	Was documented	Chart renders
podSecurity.capabilities	SETFCAP, AUDIT_WRITE, MKNOD among 9	those three never granted; DAC_READ_SEARCH, SYS_RESOURCE, NET_RAW granted and undocumented
podSecurity.volumes	[configMap, secret, hostPath]	also emptyDir
securityContextConstraints.seLinuxContext	type: gremlin.process	type: spc_t, level: s0-s0:c0.c1023
container.driver	any	linux (same code path — cosmetic)
secret.name	gremlin-team-cert	gremlin-team-cert unmanaged, gremlin-secret managed

The capabilities one is the most consequential: a user who trusts the table and re-asserts it with --set silently strips DAC_READ_SEARCH, SYS_RESOURCE and NET_RAW, which values.yaml documents as required for dependency discovery, Certificate Expiry with CIDR args, and container Process Exhaustion.

On SELinux, only the SCC row was wrong — the PSP row directly above it was already correct and is unchanged. values.yaml explains why spc_t matters: OpenShift/CRI-O runs hostPID=true pods as spc_t and any other value is ignored, so the documented value would have broken an OpenShift install.

values.yaml

• The container.driver comment said containerd implies /run/containers/containers.sock in three places. No template mounts that path; containerDrivers.containerd-linux.runtimeSocket already had the correct /run/containerd/containerd.sock. Fixed all three.
• chao.serviceAccount.create's comment was a copy of chao.create's, telling readers it controls whether the Deployment is installed. It controls the ServiceAccount, ClusterRole/gremlin-watcher and its binding.
• Added a commented gremlin.secret.name entry so the key is discoverable from the file the README calls the full reference. It is intentionally computed in _helpers.tpl rather than declared, so it stays commented.
• The tag-escaping comment pointed at github.com/gremlin/helm/issues/8, which 404s. Replaced with a pointer to the worked example.

Added

• Prerequisites now state that a default install creates four cluster-scoped objects (ClusterRole/gremlin-metadata-reader, ClusterRoleBinding/gremlin-metadata-reader, ClusterRole/gremlin-watcher, ClusterRoleBinding/chao), name the two serviceAccount.create=false escape valves, and note that using them requires pre-created ServiceAccounts named exactly gremlin and chao because both names are fixed in the pod specs. Also Helm 3.
• gremlin.serviceUrl — honoured by the chart, present in every values file generated at app.gremlin.com/getting-started, and documented only in the sibling gremlin-integrations README.

Deliberately not in this PR

These need a decision from someone who owns the feature, not a docs edit:

• ~30 gremlin.tls.identity.* / chao.tls.identity.* keys appear in no Markdown anywhere in the repo. Three strategies, dedicated templates, dedicated tests. Whether they are customer-facing or internal is a product call — but silence seems like the wrong answer either way.
• Version pinning. Chart.yaml has no appVersion, image.tag is latest, and minimumAppVersion: 2.66.0 has no consumer anywhere in agent, service, webapp or helm — it is informational and unenforced. image.tag is the lever, but nothing records an agent↔chao version mapping, so guidance would be guesswork.
• What actually breaks if the cluster-scoped RBAC is dropped. No agent code was found reading the nodes resource that gremlin-metadata-reader grants, but that is a grep negative, not proof, and Chao was not examined. The Prerequisites wording above says only what the chart creates, and advises checking with support before disabling.
• Three chart bugs (not docs): chao.create=false still renders ServiceAccount/chao, ClusterRole/gremlin-watcher and ClusterRoleBinding/chao because the template gates on chao.serviceAccount.create; enabling PSP and SCC together renders two RoleBindings both named default:gremlin; and GREMLIN_CLIENT_TAGS at _daemonset.tpl:178 is missing | quote, so the default renders a bare value: and a tag containing YAML metacharacters would corrupt the manifest.
• One thing needs 60 seconds of human confirmation before merge: the credential-download click path in the Installation section. The audit's browser was blocked from re-verifying the app's current labels, and the redirect involved is client-side so curl cannot see it. The field observation was that app.gremlin.com/settings/teams lands on Company Options, that there is no Configuration tab, and that certificates live under Team Settings → Details. That text is left unchanged in this PR rather than rewritten from an unverified observation.

[Copilot]

Pull request overview

This PR updates the Gremlin Helm chart documentation (and related values.yaml comments/defaults) to make the install/uninstall flows copy-pasteable on a clean cluster and to align documented defaults/keys with what the chart actually renders.

Changes:

• Add --create-namespace to install snippets across READMEs so first-time installs don’t fail on a missing namespace.
• Fix Helm 3 uninstall guidance and refresh the “Example Usage” --set syntax to properly escape commas and use the documented key.
• Align gremlin/values.yaml comments/defaults and gremlin/README.md configuration table entries with current chart behavior (capabilities, SCC SELinux context, secret naming, etc.).

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
README.md	Updates top-level install snippets to create the gremlin namespace during install.
gremlin/values.yaml	Corrects/clarifies several values comments and adjusts the default container driver value to match documented behavior.
gremlin/README.md	Expands prerequisites, fixes config table defaults, updates example usage and uninstall instructions.
gremlin/examples/drivers/README.md	Updates the driver example install snippet to create the namespace.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.