Docs update: storing tokens in secrets
I was cleaning up content moved from docs/install/kubernetes.md
to docs/install/kubernetes_configuration.md
in !5054 (merged), and stumbled into a section I can't figure out what to do with. That section is holding up the rest of the MR, so I'll copy it here with extra info.
The raw content
Expand to see the markdown
## Store registration tokens or runner tokens in secrets
> - [Introduced](https://gitlab.com/gitlab-org/charts/gitlab-runner/-/merge_requests/405) in GitLab 16.1.
To register a runner created in the GitLab UI, you specify the `runnerToken` in `values.yml`. GitLab shows
the `runnerToken` briefly in the UI when you create the runner.
Storing tokens in `values.yml` is a security risk, especially if you commit them to Git. Instead, store the values of these tokens in a
[Kubernetes secret](https://kubernetes.io/docs/concepts/configuration/secret/), and
then update the `runners.secret` value in `values.yml` with the name of the secret.
If you have an existing registered runner and want to use that, set the `runner-token` with the token used
to identify that runner. If you want to have a new runner registered you can set the
`runner-registration-token` with a
[registration token](https://docs.gitlab.com/ee/ci/runners/) ([deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/102681)).
For example:
1. Create a secret with registration token:
```yaml
apiVersion: v1
kind: Secret
metadata:
name: gitlab-runner-secret
type: Opaque
data:
runner-registration-token: "" # need to leave as an empty string for compatibility reasons
runner-token: "REDACTED"
```
```shell
kubectl apply --namespace <NAMESPACE> -f gitlab-runner-secret.yaml
```
1. Configure the following in `values.yaml`:
```yaml
runners:
secret: gitlab-runner-secret
```
This example uses the secret `gitlab-runner-secret` and takes the value of
`runner-token` to register the runner.
NOTE:
If your secret management solution doesn't allow you to set empty string for `runner-registration-token`,
you can set it to any string. When `runner-token` is present, the string is ignored.
The questions
The discussion thread:
-
@aqualls: question (blocking): Technical reviewer, I don't know what to do with this section. Some of what's here was deprecated Deprecation - runnerRegistrationToken in the Gi... (gitlab!102681 - merged) in 15.6, and removed in 16.0. I have no subject matter knowledge, so I don't know whether to delete the section or get it rewritten by someone who knows the answer.
-
@ggeorgiev_gitlab
:@ratchade
Might know something about this. -
@ratchade: It seems to be related to this user feedbacks. I traced this note back to this specific MR: !4276 (merged). Even though
registration-token
are deprecated, the property is still checked in the GitLab Runner Operator code (took a note to have it remove during the next milestone).WDYT if we have a follow-up issue cleanup this note when the GitLab Runner Operator codebase is also cleaned ?
Other pages to update
When this content returns, we should update:
-
docs/install/kubernetes.md
: Re-link the lineSet this token directly or store it in a secret
in -
docs/install/kubernetes_troubleshooting.md
: Review the subheadingFATAL: Runner configuration is reserved
to see if changes are needed -
docs/install/kubernetes_troubleshooting.md
: Restore the crosslink in the subheading## Error: Unable to mount volumes for pod
Related items
- Related to Break apart Helm chart optional config into new... (!5054 - merged)
- Related to Take in account registration token from secret (gitlab-org/charts/gitlab-runner!405 - merged)
- Related to Deprecation - runnerRegistrationToken in the Gi... (gitlab!102681 - merged)
- Related to Deprecation - runnerRegistrationToken in GitLab... (gitlab#381111 - closed) ← has a lot of MRs attached to it
- https://docs.gitlab.com/ee/architecture/blueprints/runner_tokens/#helm-chart