Skip to content

Kubernetes Pull Secret

Allow your K3s cluster to pull game server Docker images from a private GitLab Container Registry using a Deploy Token.

Prerequisites

  • A running K3s cluster (master node set up)
  • kubectl configured and pointing to your cluster
  • Access to the GitLab project that hosts the container registry

Overview

Kubernetes needs credentials to pull images from private registries. The flow is:

flowchart LR
    A[GitLab Project] -- "Create Deploy Token\nread_registry" --> B[Deploy Token\nusername + password]
    B -- "kubectl create secret" --> C[K8s Secret\ntype: dockerconfigjson]
    C -- "Patch ServiceAccount" --> D[All pods can pull\nprivate images]

1 — Create a GitLab Deploy Token

  1. In GitLab, go to Project → Settings → Repository → Deploy Tokens.

  2. Click Add token:

    Field Value
    Name e.g. k8s-pull
    Expiration Optional — set if your security policy requires rotation
    Scopes Enable read_registry only

  3. Click Create deploy token.

  4. Copy both values — you won't see the password again:
    • DEPLOY_TOKEN_USERNAME (e.g. gitlab+deploy-token-1234)
    • DEPLOY_TOKEN_PASSWORD

Warning

Use a Deploy Token (read-only, project-scoped) for Kubernetes, not a Personal Access Token. Deploy Tokens have minimal permissions and can be revoked per-project without affecting your account.

2 — Create the Kubernetes Secret

Run the script from MIPScripts\kubes\config\:

bash 03-create-gitlab-pull-secret.sh

Or click 03 Create Pull Secret in the MIP Control Panel (Kubes → Config).

The script prompts for your Deploy Token username and password, then:

  1. Deletes any existing gitlab secret so there are no stale credentials
  2. Creates a fresh docker-registry secret named gitlab in the default namespace
  3. Patches both the default and agones-sdk ServiceAccounts with imagePullSecrets: [gitlab] — fleet pods can pull from registry.gitlab.com without adding imagePullSecrets to every fleet YAML

Once done, head back to Deploy Master Node to continue the setup.

Verify:

kubectl get secret gitlab -n default

3 — Verify

Create a test pod or let Agones allocate a game server, then check:

kubectl get pods -n default
kubectl describe pod <POD_NAME> -n default

In the events section, you should see:

Successfully pulled image "registry.gitlab.com/..."

If you see ImagePullBackOff or ErrImagePull, check:

  • The deploy token has read_registry scope
  • The secret was created in the correct namespace (default)
  • The ServiceAccount was patched

Rotating the Token

When a deploy token expires or is revoked:

  1. Create a new deploy token in GitLab (step 1).
  2. Re-run 03-create-gitlab-pull-secret.sh (or 03 Create Pull Secret in the Control Panel) — it deletes and recreates the secret automatically.
  3. The ServiceAccount patches don't need to change — they reference the secret by name.
  4. Existing pods keep running. New pods will use the updated credentials.

Quick Reference

Step How
Create / recreate secret + patch SAs bash 03-create-gitlab-pull-secret.sh or Control Panel → 03 Create Pull Secret
Verify secret kubectl get secret gitlab -n default
Verify SA patch kubectl get serviceaccount default -n default -o jsonpath='{.imagePullSecrets}'
Delete secret manually kubectl delete secret gitlab -n default