itsulu-blog-publisher/GITLAB_SETUP_GUIDE.md

GitLab Setup for Phase 3 K8s E2E Testing

Status: Action Required (User/Ops actions in GitLab UI)
Timeline: ~15 minutes total
Prerequisite: Access to both GitLab projects as admin/maintainer

---

Overview

Two GitLab actions are required to enable Phase 3 E2E testing:

1. Create GitLab Deploy Token (for K8s to pull Docker image)
2. Set KUBE_CONFIG CI/CD Variable (for K8s cluster access)

Both are UI-based and take ~5 minutes each.

---

Action 1: Create GitLab Deploy Token

Project: itsulu-odoo/itsulu-blog-publisher
Purpose: Allow K8s to pull the Docker image from GitLab container registry
Scope: Read-only registry access

Steps

1. Navigate to Deploy Tokens

   Project: itsulu-odoo/itsulu-blog-publisher
   → Settings (left sidebar)
   → Repository
   → Deploy Tokens
   

2. Create New Deploy Token

   • Name: k8s-registry-pull
   • Expires at: (optional, or 1 year from now)
   • Scopes: Check ONLY read_registry
   • Click: Create deploy token

3. Save the Credentials

   • Copy and save the displayed values:
     • Username: (usually format: <project>+<token-name>)
     • Token: (secret token value)

   ⚠️ Important: You'll only see these values once. Copy them now.

Example Output

Deploy Token Created
Username: itsulu-blog-publisher+k8s-registry-pull
Token: K1x9mPq2zL8nFvWx

Verification

Once created, you should see in the Deploy Tokens list:

• Name: k8s-registry-pull
• Scopes: read_registry
• Status: Active
• Created: Today's date

---

Action 2: Create K8s Secret from Deploy Token

Once you have the Deploy Token credentials from Action 1, provide them to create the K8s secret.

Option A: I Create the Secret (Recommended)

Provide me with:

• Deploy token username
• Deploy token token value

I'll then:

1. Create the K8s secret gitlab-docker-creds in itsulu-testing namespace
2. Verify it's working
3. Confirm ready for E2E tests

Option B: You Create the Secret Manually

If you prefer to create it yourself:

kubectl create secret docker-registry gitlab-docker-creds \
  --docker-server=registry.gitlab.com \
  --docker-username='<deploy-token-username>' \
  --docker-password='<deploy-token-token>' \
  --docker-email=noreply@gitlab.com \
  -n itsulu-testing

# Verify
kubectl get secret gitlab-docker-creds -n itsulu-testing

---

Action 3: Set KUBE_CONFIG CI/CD Variable

Project: itsulu-odoo/itsulu-blog-publisher
Purpose: Provide K8s cluster access to GitLab CI/CD pipeline
Scope: itsulu-testing namespace only

Prerequisites

You need a kubeconfig file that has access to the itsulu-testing namespace.

The kubeconfig should:

• Have context: itsulu-testing (or similar)
• Have user credentials for K8s cluster
• Have permissions to create Jobs in itsulu-testing namespace

If you don't have this, get it from the infrastructure team.

Steps

1. Encode the Kubeconfig

   # Get your kubeconfig path (usually ~/.kube/config or provided by infrastructure team)
   cat /path/to/kubeconfig | base64 -w0
   
   # On macOS:
   cat /path/to/kubeconfig | base64 | pbcopy  # Copies to clipboard
   
   # Output: Long base64 string (starts with "Y3..." and ends with "==")
   

2. Navigate to CI/CD Variables

   Project: itsulu-odoo/itsulu-blog-publisher
   → Settings (left sidebar)
   → CI/CD
   → Variables
   

3. Add New Variable

   • Key: KUBE_CONFIG
   • Value: (paste base64 kubeconfig from step 1)
   • Type: Secret
   • Protected: ✓ Yes (checked)
   • Masked: ✓ Yes (checked)
   • Click: Add variable

4. Verify You should see in the Variables list:

   • Key: KUBE_CONFIG
   • Type: Secret
   • Protected: ✓
   • Masked: ✓

Example

Input (kubeconfig file):

apiVersion: v1
clusters:
- cluster:
    server: https://itsulu-k8s.example.com:6443
  name: itsulu-testing
contexts:
- context:
    cluster: itsulu-testing
    user: itsulu-testing-admin
  name: itsulu-testing
current-context: itsulu-testing
kind: Config
...

After encoding (paste into KUBE_CONFIG variable):

YXBpVmVyc2lvbjogdjEKY2x1c3RlcnM6CisgY2x1c3RlcjoKICAgIHNlcnZlcjog...

Testing the Variable

Once set, GitLab CI/CD will have access to:

• K8s cluster via kubectl
• itsulu-testing namespace
• Ability to create/delete Jobs
• Ability to access Pod logs and copy files

The first MR will automatically test this when the e2e_tests job runs.

---

Action 4: Verify Everything is Ready

In GitLab

Project → Settings → CI/CD → Variables
Should see:
  ✓ KUBE_CONFIG (Secret, Protected, Masked)

In Kubernetes (Once Manifests Applied)

# Check secrets exist
kubectl get secrets -n itsulu-testing
# Should show: test-db-info, gitlab-docker-creds

# Test registry authentication
kubectl run --rm -it test-registry \
  --image=registry.gitlab.com/itsulu-odoo/itsulu-blog-publisher:latest \
  --overrides='{"spec":{"imagePullSecrets":[{"name":"gitlab-docker-creds"}]}}' \
  -n itsulu-testing \
  -- /bin/sh -c "echo 'Registry pull successful'"

# Test database connection
kubectl run --rm -it test-db \
  --image=postgres:15-alpine \
  -n itsulu-testing \
  -- psql -h test-db-svc -U odoo_test -d odoo_template -c "SELECT 1"

---

Troubleshooting

Issue	Solution
"Deploy Token created but I can't see the token value"	Deploy tokens only show once. You must have copied it before clicking away. Create a new token.
"KUBE_CONFIG variable appears in pipeline logs"	It should be masked. If visible, check the "Masked" checkbox in variable settings.
"Invalid kubeconfig" error in CI/CD pipeline	Check the base64 encoding is correct: echo "KUBE_CONFIG_VALUE" | base64 -d should be valid YAML.
"Permission denied: Jobs" error in e2e_tests job	ServiceAccount test-runner missing Job permissions. Check RBAC in K8s.
"ErrImagePull" in K8s job	GitLab registry credentials missing. Run Action 1 + 2.

---

Summary

✅ When You're Done

• Created deploy token k8s-registry-pull with read_registry scope
• Provided me deploy token credentials (username + token)
• I created K8s secret gitlab-docker-creds
• You set KUBE_CONFIG CI/CD variable (base64 kubeconfig)
• You verified variables in GitLab Settings → CI/CD

✅ Then I Will

• Apply K8s manifests to itsulu-testing namespace
• Initialize template database with Odoo modules
• Confirm everything is ready

✅ Then You Can

• Create an MR in itsulu-blog-publisher
• Watch E2E tests run automatically on K8s cluster
• Download test artifacts from GitLab

---

Timeline

1. Action 1: Create deploy token (~2 min)
2. Action 2a: Provide credentials to me (~1 min)
3. Action 2b: I create K8s secret (~1 min)
4. Action 3: Set KUBE_CONFIG variable (~5 min)
5. Verification: Test connectivity (~5 min)
6. Ready for K8s setup: ~15 min total

---

Next Steps

1. Follow Actions 1-3 above
2. Provide deploy token credentials (username + token)
3. Provide kubeconfig file or base64-encoded kubeconfig
4. I'll handle K8s operations (apply manifests + init template DB)
5. Create MR to trigger first E2E test run

---

Questions? See:

• K8S_DEPLOYMENT_SETUP.md — Full K8s setup guide
• PHASE3_K8S_DEPLOYMENT_READY.md — Architecture overview
• kubernetes/itsulu-testing/README.md — Infrastructure details