diff --git a/GITLAB_SETUP_GUIDE.md b/GITLAB_SETUP_GUIDE.md new file mode 100644 index 0000000..51921c0 --- /dev/null +++ b/GITLAB_SETUP_GUIDE.md @@ -0,0 +1,280 @@ +# 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: `+`) + - **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: + +```bash +kubectl create secret docker-registry gitlab-docker-creds \ + --docker-server=registry.gitlab.com \ + --docker-username='' \ + --docker-password='' \ + --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** + ```bash + # 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): +```yaml +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) + +```bash +# 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](K8S_DEPLOYMENT_SETUP.md) — Full K8s setup guide +- [PHASE3_K8S_DEPLOYMENT_READY.md](PHASE3_K8S_DEPLOYMENT_READY.md) — Architecture overview +- [kubernetes/itsulu-testing/README.md](../git/kubernetes/itsulu-testing/README.md) — Infrastructure details