Restructure Operator configuration page and document UID mismatch workarounds

What does this MR do?

Improves docs/configuration/configuring_runner_operator.md in two areas.

Reworked section for helper/build container UID mismatch:

  • Renames "Matching helper container and build container user ID and group ID" to "Mismatching user ID and group ID for helper container and build container" so the heading describes the problem rather than one solution. (Only auto-generated docs-locale files reference the old anchor; they are regenerated from the source page.)
  • Restructures the section: it now states up front that the mismatch causes two problems (Git dubious ownership errors, cache permission errors), presents the shared preferred solution (matching UIDs via the build container security context), then documents per-problem workarounds for cases where the build container UID cannot be changed:
    • dubious ownership: configure Git's safe.directory with git config --global --add safe.directory $CI_PROJECT_DIR in before_script. This is safe because HOME must already point to a writable directory (see the "Overriding the HOME environment variable" section).
    • Cache permission errors (new content): the OCP helper image archives and extracts cache files as UID 1001, so a non-root build container with a different UID can restore the cache but cannot write to it (Permission denied; chown in before_script fails since the build user does not own the files). Workaround: chmod -R 777 on the cache directory in after_script so permissions preserved in the tar archive make subsequent restores writable by any UID.

Page restructuring to fix incorrect heading nesting:

  • Clarifies that the non-root build image requirement applies by default (the anyuid SCC section describes how to change it).
  • "Overriding the HOME environment variable" is no longer nested under "Root vs non-root".
  • "Watch out for security context constraints", "Run as anyuid security context constraints", "Mismatching user ID and group ID for helper container and build container", and "Configure SETFCAP" are no longer nested under "Overriding locked variable"; they are now standalone troubleshooting entries.
  • "Using FIPS Compliant GitLab Runner" is moved out of Troubleshooting into its own top-level configuration section (it describes configuration, not an error fix).
  • "Register GitLab Runner by using a self-signed certificate" and "Register GitLab Runner with an external URL that points to an IP address" are no longer nested under the FIPS section; they are standalone troubleshooting entries.
  • All patch-related sections (Patch structure, Patching the runner pod template, Patching the runner deployment template, Patch order, Examples, Best practices) are grouped under a single new top-level "Patching" section. Heading text is unchanged, so existing anchors (for example, #patching-the-runner-pod-template linked from the Operator properties table) still resolve.

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.
Edited by Ben Bodenmiller

Merge request reports

Loading
Loading