Document that the Operator overrides the template namespace

Andrew Dunnrequested to merge
docs-operator-namespace-known-issue into main

What does this MR do?

A namespace set in a configuration template for the GitLab Runner Operator has no effect. By default, job pods start in the namespace of the Runner resource. The Operator sets KUBERNETES_NAMESPACE on the runner pod (where it is set, where the value comes from), and GitLab Runner prefers that value over the template at registration, as the registration docs describe.

This MR adds kubernetes.namespace to the known-issue table on the Operator configuration page, next to the other settings that need an environment variable. The default value is the namespace of the Runner resource.

With Operator v1.54.0 and GitLab Runner v19.5.0, job pods run in:

  • the namespace of the Runner resource, when the template sets namespace or sets nothing;
  • the namespace in KUBERNETES_NAMESPACE, when the ConfigMap named in spec.env of the Runner resource sets it;
  • the namespace in spec.namespace of the Runner resource, when that field is set.

Outside the Operator, gitlab-runner register with KUBERNETES_NAMESPACE set also replaces the template's namespace. gitlab-runner run with the same namespace in config.toml, and no registration step, keeps it.

The Operator MR gitlab-org/gl-openshift/gitlab-runner-operator!306 changes this precedence. The row can go once that ships.

Related issues

gitlab-org/gl-openshift/gitlab-runner-operator#229 (closed) reports the same precedence, and the table already links it. The bot auto-closed it as stale on 21 September, and the Operator MR above still closes it.

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.

An AI coding assistant wrote this change. The assistant also checked the Operator behavior against environments.go at Operator v1.54.0 and the text of the linked Operator MR and issue, ran each described behavior on a disposable Kubernetes cluster on a GCE VM, and ran markdownlint, lychee and Vale on the changed page.

Merge request reports