Document the default RBAC role the Helm chart creates

Andrew Dunnrequested to merge
docs/helm-rbac-default-role into main

What does this MR do?

  • Documents that rbac.create: true gives the runner service account all verbs on all resources in the core API group when rbac.rules is empty.
  • Adds a short topic, "Limit the permissions the chart grants", that explains how rbac.rules changes the role.
  • Links to it from the rbac requirement on the install page.

The change adds 18 lines to two pages. It changes no chart behavior.

Why

The install page says operators must set rbac: { create: true }. With rbac.rules empty, which is the default, the chart renders this role:

rules:
- apiGroups: [""]
  resources: ["*"]
  verbs: ["*"]

That role is wider than the permissions the runner needs, which the Kubernetes executor page lists. A namespace administrator who is not a cluster administrator cannot install the chart with it, because Kubernetes rejects a role that grants more than its creator holds (gitlab-org/charts/gitlab-runner#38 (moved)). No runner page says the default is a wildcard or that rbac.rules narrows it.

flowchart TD
    A["rbac.create: true"] --> B{"rbac.rules empty?"}
    B -->|"yes, the default"| C["Role: core API group, all resources, all verbs"]
    B -->|"no"| D["Role: only the listed rules"]
    D --> E["A rule that omits resources or verbs, or leaves either empty, gets *"]

How it was checked

Checked with helm template on chart v0.93.0:

  • Default values render the all-access rule above.
  • One rule with resources and verbs replaces it.
  • A rule with no verbs, or with verbs: [], renders verbs: ["*"].
  • rbac.clusterWideAccess: true renders a ClusterRole.
  • templates/role.yaml is identical at v0.93.0 and on main.

Related issues

Author's checklist

If you are a GitLab team member and only adding documentation, do not add any of the following labels:

  • ~"frontend"
  • ~"backend"
  • ~"type::bug"
  • ~"database"

These labels cause the MR to be added to code verification QA issues.

Reviewer's checklist

Documentation-related MRs should be reviewed by a Technical Writer for a non-blocking review, based on Documentation Guidelines and the Style Guide.

If you aren't sure which tech writer to ask, use roulette or ask in the #docs Slack channel.

  • If the content requires it, ensure the information is reviewed by a subject matter expert.
  • Technical writer review items:
    • Ensure docs metadata is present and up-to-date.
    • Ensure the appropriate labels are added to this MR.
    • Ensure a release milestone is set.
    • If relevant to this MR, ensure content topic type principles are in use, including:
      • The headings should be something you'd do a Google search for. Instead of Default behavior, say something like Default behavior when you close an issue.
      • The headings (other than the page title) should be active. Instead of Configuring GDK, say something like Configure GDK.
      • Any task steps should be written as a numbered list.
      • If the content still needs to be edited for topic types, you can create a follow-up issue with the docs-technical-debt label.
  • Review by assigned maintainer, who can always request/require the above reviews. Maintainer's review can occur before or after a technical writer review.

AI disclosure

An AI coding assistant wrote this change. The assistant also checked each claim against the chart templates and values.yaml at chart v0.93.0, ran each described behavior with helm template on that chart, and ran Vale and markdownlint-cli2 with this project's configuration on the changed pages on a local workstation.

Merge request reports