mirror of
https://gitlab.com/itsulu-odoo/itsulu-blog-publisher.git
synced 2026-05-30 23:41:23 +00:00
docs: Add GitLab setup guide for Phase 3 E2E testing
Created comprehensive guide for GitLab UI setup required for Phase 3: Actions: 1. Create GitLab Deploy Token (read_registry scope) 2. Provide credentials for K8s secret creation 3. Set KUBE_CONFIG CI/CD variable (base64 kubeconfig) Includes: - Step-by-step instructions for each action - Screenshots/examples of expected outputs - Troubleshooting for common issues - Timeline and next steps - Verification commands for K8s cluster Timeline: ~15 minutes total for all GitLab UI actions Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
This commit is contained in:
parent
dcda5be0dd
commit
0d88ffdd6e
1 changed files with 280 additions and 0 deletions
280
GITLAB_SETUP_GUIDE.md
Normal file
280
GITLAB_SETUP_GUIDE.md
Normal file
|
|
@ -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: `<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:
|
||||
|
||||
```bash
|
||||
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**
|
||||
```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
|
||||
Loading…
Reference in a new issue