Connecting to a Cell's Toolbox Pod

This guide covers how to connect to a cell’s toolbox pod for debugging and troubleshooting purposes.

Prerequisites

Follow the breakglass access guide to request the appropriate level of access.

Once you have the right level of access, you should get the Kubernetes cluster credentials using the appropriate procedure depending on the /cloud_provider field in the tenant model of the Cell:

Connecting to the Toolbox Pod

Find the Toolbox Pod

List the toolbox pods in the default namespace:

$ kubectl get pod --namespace default --selector app=toolbox

Example output:

NAME                              READY   STATUS                  RESTARTS      AGE
gitlab-toolbox-8c6bff946-8lt4v    1/1     Running                 0             5d

Execute a Shell in the Toolbox Pod

Execute a bash shell in the toolbox container:

kubectl exec -it <toolbox-pod-name> --container toolbox -- bash

Example:

kubectl exec -it gitlab-toolbox-8c6bff946-8lt4v --container toolbox -- bash

You should now have a shell inside the toolbox pod:

git@gitlab-toolbox-8c6bff946-8lt4v:/$

Common Operations

Check Migration Status

View the status of all database migrations:

gitlab-rails db:migrate:status

Filter for specific migrations:

gitlab-rails db:migrate:status | grep -E '<migration_version>'

Run Migrations Manually

Use the db-migrate script to execute migrations in the correct order (regular migrations first, then post-deployment migrations):

./scripts/db-migrate

This script will:

Check if migrations are up-to-date
Run regular migrations (db:migrate)
Run post-deployment migrations
Perform custom instance setup

Troubleshooting

No Toolbox Pods Found

If no toolbox pods are found, check:

You’re in the correct namespace (default is default)
The toolbox deployment exists: kubectl get deployments -l app=toolbox
Check for any deployment issues: kubectl describe deployment <toolbox-deployment>