From eed53006c1eb3e97628ebc632dcadf3d20267cf5 Mon Sep 17 00:00:00 2001 From: Danijel Simeunovic Date: Sat, 18 Apr 2026 23:10:18 +0200 Subject: [PATCH] docs --- README.md | 20 +++++------ docs/DEVELOPER-GUIDE.md | 48 +++++++++++++------------- docs/GITOPS-ARCHITECTURE.md | 20 +++++------ docs/OPERATIONS-RUNBOOK.md | 67 +++++++++++++++++++------------------ docs/REFERENCE.md | 12 +++---- 5 files changed, 84 insertions(+), 83 deletions(-) diff --git a/README.md b/README.md index 9095ee0..d419e33 100644 --- a/README.md +++ b/README.md @@ -146,12 +146,12 @@ This repository contains the complete GitOps configuration for our Kubernetes cl |------------|---------|-----------|-----------| | **[launchpad](https://git.forteapps.net/Forte/launchpad)** (this repo) | ArgoCD Applications, cluster resources | Platform / DevOps engineers | ✅ Often | | **[forte-helm](https://git.forteapps.net/Forte/forte-helm)** | Generic Helm chart templates | Platform engineers | ❌ Rarely | -| **[helm-values](ssh://git@git.forteapps.net:2222/Forte/helm-prod-values.git)** | App-specific configuration & versions | Developers / CI pipelines | ✅ Sometimes | +| **[helm-prod-values](ssh://git@git.forteapps.net:2222/Forte/helm-prod-values.git)** | App-specific configuration & versions | Developers / CI pipelines | ✅ Sometimes | ### GitOps Workflow ``` -Developer commits code → CI/CD builds image → Updates helm-values → ArgoCD syncs → Deployed to cluster +Developer commits code → CI/CD builds image → Updates helm-prod-values → ArgoCD syncs → Deployed to cluster ``` **Learn more**: [GitOps Architecture - GitOps Workflow](docs/GITOPS-ARCHITECTURE.md#gitops-workflow) @@ -166,7 +166,7 @@ Developer commits code → CI/CD builds image → Updates helm-values → ArgoCD **Quick version**: 1. Create `apps/myapp.yaml` (ArgoCD Application manifest) -2. Create `helm-values/myapp/values.yaml` (configuration) +2. Create `helm-prod-values/myapp/values.yaml` (configuration) 3. Create sealed secrets if needed 4. Commit and push - ArgoCD auto-syncs! @@ -175,8 +175,8 @@ Developer commits code → CI/CD builds image → Updates helm-values → ArgoCD **See detailed guide**: [Developer Guide - Updating an Existing Application](docs/DEVELOPER-GUIDE.md#updating-an-existing-application) **Quick version**: -- **Update code**: Push to app repo → CI/CD updates image tag in helm-values -- **Update config**: Edit `helm-values/myapp/values.yaml` → commit → push +- **Update code**: Push to app repo → CI/CD updates image tag in helm-prod-values +- **Update config**: Edit `helm-prod-values/myapp/values.yaml` → commit → push ### Manage Secrets @@ -204,7 +204,7 @@ git push **Quick version**: ```yaml -# In helm-values/myapp/values.yaml +# In helm-prod-values/myapp/values.yaml # Token-based auth (simple) auth: @@ -366,7 +366,7 @@ kubectl patch application myapp -n argocd \ ### Multi-Source Pattern Applications reference both: 1. **Helm charts** from `forte-helm` (templates) -2. **Values** from `helm-values` (configuration) +2. **Values** from `helm-prod-values` (configuration) This separates reusable templates from environment-specific config. @@ -435,7 +435,7 @@ Applications deploy in order using `argocd.argoproj.io/sync-wave`: ### Adding a New Application 1. Read [Developer Guide - Deploying Your First Application](docs/DEVELOPER-GUIDE.md#deploying-your-first-application) 2. Create ArgoCD Application manifest in `apps/` -3. Create Helm values in `helm-values/` +3. Create Helm values in `helm-prod-values/` 4. Create sealed secrets if needed 5. Commit and push - ArgoCD handles the rest! @@ -485,8 +485,8 @@ Documentation lives in `docs/`. To update: - [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) ### Related Repositories -- [forte-helm](https://github.com/fortedigital/forte-helm) - Helm chart templates -- [helm-values](git@github.com:fortedigital/helm-values.git) - Application values +- [forte-helm](https://git.forteapps.net/Forte/forte-helm) - Helm chart templates +- [helm-prod-values](git@github.com:fortedigital/helm-prod-values.git) - Application values --- diff --git a/docs/DEVELOPER-GUIDE.md b/docs/DEVELOPER-GUIDE.md index 9a2f127..8f4402f 100644 --- a/docs/DEVELOPER-GUIDE.md +++ b/docs/DEVELOPER-GUIDE.md @@ -96,10 +96,10 @@ You'll need read/write access to these repositories: cd launchpad ``` -2. **helm-values** (Values repo) +2. **helm-prod-values** (Values repo) ```bash git clone https://git.forteapps.net/Forte/helm-prod-values.git - cd helm-values + cd helm-prod-values ``` 3. **forte-helm** (Chart repo - read-only for most developers) @@ -175,13 +175,13 @@ npm run dev │ - GitHub Actions builds image │ │ - Pushes to container registry (GHCR, Docker Hub) │ │ - Tags with version (e.g., v2.0.4) │ -│ - Updates helm-values repository with new tag │ +│ - Updates helm-prod-values repository with new tag │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Step 3: GitOps Sync (Automated) │ -│ - ArgoCD detects change in helm-values │ +│ - ArgoCD detects change in helm-prod-values │ │ - Pulls updated configuration │ │ - Syncs to Kubernetes cluster │ │ - Sends Slack notification on success/failure │ @@ -201,7 +201,7 @@ Our setup uses three repositories: | Repository | Purpose | Who Edits | How Often | |------------|---------|-----------|-----------| | **forte-helm** | Helm chart templates (generic, reusable) | Platform engineers | ❌ Rarely | -| **helm-values** | Application configuration (image tag, env vars) | Developers / CI pipelines | ✅ Sometimes | +| **helm-prod-values** | Application configuration (image tag, env vars) | Developers / CI pipelines | ✅ Sometimes | | **launchpad** | ArgoCD Applications (what gets deployed) | Platform / DevOps engineers | ✅ Per new app | ### Example: Deploying "myapp" @@ -223,7 +223,7 @@ spec: value: {{ .Values.app.port }} ``` -#### Repository: `helm-values` (Your App Config) +#### Repository: `helm-prod-values` (Your App Config) ```yaml # myapp/values.yaml # Your app's specific configuration @@ -248,13 +248,13 @@ metadata: namespace: argocd spec: sources: - - repoURL: https://github.com/fortedigital/forte-helm + - repoURL: https://git.forteapps.net/Forte/forte-helm path: forteapp helm: valueFiles: - $values/myapp/values.yaml - - repoURL: git@github.com:fortedigital/helm-values.git + - repoURL: git@github.com:fortedigital/helm-prod-values.git ref: values destination: @@ -316,10 +316,10 @@ Ensure your app repository has: docker build -t ghcr.io/fortedigital/hello-world:${{ steps.version.outputs.VERSION }} . docker push ghcr.io/fortedigital/hello-world:${{ steps.version.outputs.VERSION }} - - name: Update helm-values + - name: Update helm-prod-values run: | - git clone git@github.com:fortedigital/helm-values.git - cd helm-values + git clone git@github.com:fortedigital/helm-prod-values.git + cd helm-prod-values mkdir -p hello-world cat > hello-world/values.yaml < -- env # Check if secrets exist kubectl get secrets -n myapp -# Increase resources in helm-values +# Increase resources in helm-prod-values vim ~/dev/k8s/helm-prod-values/myapp/values.yaml ``` @@ -1649,7 +1649,7 @@ If you're stuck: ### Configuration Management ✅ **DO**: -- Keep configuration in `helm-values` repository +- Keep configuration in `helm-prod-values` repository - Use environment variables for config - Document what each value does - Use reasonable resource limits diff --git a/docs/GITOPS-ARCHITECTURE.md b/docs/GITOPS-ARCHITECTURE.md index c1e3207..524023c 100644 --- a/docs/GITOPS-ARCHITECTURE.md +++ b/docs/GITOPS-ARCHITECTURE.md @@ -47,7 +47,7 @@ This Kubernetes cluster uses a **GitOps approach** powered by **ArgoCD**, where │ │ │ │ │ │ └────────► Update image tag ─┴──────────────────────────┘ - in helm-values │ + in helm-prod-values │ │ ▼ ┌────────────────────────────────┐ @@ -184,7 +184,7 @@ launchpad/ --- ### 2. **Helm Charts Repository** -**Repository**: `https://github.com/fortedigital/forte-helm` +**Repository**: `https://git.forteapps.net/Forte/forte-helm` **Purpose**: Reusable Helm chart templates for Forte applications **Location**: `C:\dev\k8s\forte-helm` @@ -218,7 +218,7 @@ forte-helm/ --- ### 3. **Helm Values Repository** -**Repository**: `git@github.com:fortedigital/helm-values.git` +**Repository**: `git@github.com:fortedigital/helm-prod-values.git` **Purpose**: Environment-specific configuration for each application **Location**: `C:\dev\k8s\helm-prod-values` @@ -279,7 +279,7 @@ app-repository/ 2. Build Docker image 3. Tag with version (e.g., `v2.0.4`) 4. Push to container registry (GHCR, Docker Hub, etc.) -5. Update image tag in `helm-values` repository +5. Update image tag in `helm-prod-values` repository 6. ArgoCD detects change and syncs automatically --- @@ -340,13 +340,13 @@ Applications like `mcp10x` and `musicman` use multiple sources: ```yaml spec: sources: - - repoURL: https://github.com/fortedigital/forte-helm + - repoURL: https://git.forteapps.net/Forte/forte-helm path: forteapp # Helm chart templates helm: valueFiles: - $values/mcp10x/values.yaml # Reference to second source - - repoURL: git@github.com:fortedigital/helm-values.git + - repoURL: git@github.com:fortedigital/helm-prod-values.git targetRevision: HEAD ref: values # Named reference ``` @@ -414,8 +414,8 @@ jobs: - name: Update Helm values run: | - git clone git@github.com:fortedigital/helm-values.git - cd helm-values/app + git clone git@github.com:fortedigital/helm-prod-values.git + cd helm-prod-values/app sed -i "s/tag: .*/tag: $VERSION/" values.yaml git commit -am "Update app to $VERSION" git push @@ -432,7 +432,7 @@ jobs: - Syncs application to cluster 2. **Helm Values Change**: - - CI/CD updates `helm-values/myapp/values.yaml` + - CI/CD updates `helm-prod-values/myapp/values.yaml` - ArgoCD detects change - Pulls new Helm chart with updated values - Applies to cluster @@ -639,7 +639,7 @@ Notifications include: ✅ **DO**: - Follow the `forteapp` chart pattern - Use semantic versioning for image tags -- Update helm-values via CI/CD +- Update helm-prod-values via CI/CD - Test locally with Docker Compose - Document environment variables diff --git a/docs/OPERATIONS-RUNBOOK.md b/docs/OPERATIONS-RUNBOOK.md index 822ba97..a02a239 100644 --- a/docs/OPERATIONS-RUNBOOK.md +++ b/docs/OPERATIONS-RUNBOOK.md @@ -85,7 +85,8 @@ kubectl get applications -n argocd 1. **Configure DNS** for ingress domains: - `argocd.127.0.0.1.nip.io` (local dev) - - `*.forteapps.net` (production) + - `*.forteapps.net` (dev) + - `*.fortedigital.com` (production) 2. **Verify Let's Encrypt certificates**: ```bash @@ -107,7 +108,7 @@ kubectl get applications -n argocd ### ArgoCD Repository Access Setup -ArgoCD needs SSH access to private Git repositories to pull manifests and Helm values. This section covers setting up deploy keys for GitHub repositories. +ArgoCD needs SSH access to private Git repositories to pull manifests and Helm values. This section covers setting up deploy keys for Gitea repositories. #### Why Deploy Keys? @@ -119,7 +120,7 @@ ArgoCD needs SSH access to private Git repositories to pull manifests and Helm v #### Prerequisites - kubectl access to the cluster -- Write access to the GitHub repository +- Write access to the Gitea repository - ArgoCD installed and running #### Setup Procedure @@ -138,16 +139,16 @@ ssh-keygen -t rsa -b 4096 -C "argocd-deploy-key-launchpad" -f argocd-deploy-key This creates two files: - `argocd-deploy-key` - Private key (keep secret) -- `argocd-deploy-key.pub` - Public key (add to GitHub) +- `argocd-deploy-key.pub` - Public key (add to Gitea) -**Step 2: Add Public Key to GitHub** +**Step 2: Add Public Key to Gitea** 1. Copy the public key: ```bash cat argocd-deploy-key.pub ``` -2. Go to GitHub repository settings: +2. Go to Gitea repository settings: - Navigate to: `https://git.forteapps.net/Forte/launchpad/settings/keys` - Or: Repository → Settings → Deploy keys @@ -157,12 +158,12 @@ This creates two files: - ☐ Allow write access (leave unchecked - read-only is sufficient) - Click **"Add key"** -4. Repeat for the `helm-values` repository if it's private: +4. Repeat for the `helm-prod-values` repository if it's private: ```bash - # Generate separate key for helm-values repo - ssh-keygen -t ed25519 -C "argocd-deploy-key-helm-values" -f argocd-helm-values-key -N "" + # Generate separate key for helm-prod-values repo + ssh-keygen -t ed25519 -C "argocd-deploy-key-helm-prod-values" -f argocd-helm-prod-values-key -N "" - # Add to: https://github.com/fortedigital/helm-values/settings/keys + # Add to: https://git.forteapps.net/Forte/helm-prod-values/settings/keys ``` **Step 3: Create Kubernetes Secret** @@ -270,7 +271,7 @@ rm /tmp/test-repo-access.yaml # Generate new key ssh-keygen -t ed25519 -C "argocd-deploy-key-$(date +%Y%m)" -f argocd-new-key -N "" - # Add new public key to GitHub (keep old key for now) + # Add new public key to Gitea (keep old key for now) # Update Kubernetes secret kubectl create secret generic repo-launchpad \ @@ -278,7 +279,7 @@ rm /tmp/test-repo-access.yaml --namespace=argocd \ --dry-run=client -o yaml | kubectl apply -f - - # Test access, then remove old deploy key from GitHub + # Test access, then remove old deploy key from Gitea # Clean up shred -u argocd-new-key @@ -289,7 +290,7 @@ rm /tmp/test-repo-access.yaml # List all repository secrets kubectl get secrets -n argocd -l argocd.argoproj.io/secret-type=repository - # Review deploy keys in GitHub + # Review deploy keys in Gitea # Visit: https://git.forteapps.net/Forte/launchpad/settings/keys ``` @@ -312,16 +313,16 @@ kubectl get secret repo-launchpad -n argocd -o yaml | grep argocd.argoproj.io/se # Check ArgoCD application controller logs kubectl logs -n argocd deployment/argocd-application-controller | grep -i "permission denied" -# Verify deploy key is added to GitHub +# Verify deploy key is added to Gitea # Visit: https://git.forteapps.net/Forte/launchpad/settings/keys ``` **Issue: "Host key verification failed"** ```bash -# Add GitHub to known_hosts +# Add Gitea to known_hosts kubectl exec -n argocd deployment/argocd-repo-server -- \ - ssh-keyscan github.com >> ~/.ssh/known_hosts + ssh-keyscan git.forteapps.net >> ~/.ssh/known_hosts # Or disable strict host key checking (less secure) kubectl patch secret repo-launchpad -n argocd \ @@ -346,16 +347,16 @@ kubectl rollout restart deployment argocd-application-controller -n argocd #### Multiple Repository Setup -For the three-repository pattern (launchpad, forte-helm, helm-values): +For the three-repository pattern (launchpad, forte-helm, helm-prod-values): ```bash # 1. launchpad (main config repo) ssh-keygen -t ed25519 -C "argocd-launchpad" -f key-sturdy -N "" # Add key-sturdy.pub to: https://git.forteapps.net/Forte/launchpad/settings/keys -# 2. helm-values (private values repo) -ssh-keygen -t ed25519 -C "argocd-helm-values" -f key-helm-values -N "" -# Add key-helm-values.pub to: https://github.com/fortedigital/helm-values/settings/keys +# 2. helm-prod-values (private values repo) +ssh-keygen -t ed25519 -C "argocd-helm-prod-values" -f key-helm-prod-values -N "" +# Add key-helm-prod-values.pub to: https://git.forteapps.net/Forte/helm-prod-values/settings/keys # 3. forte-helm (private helm charts repo) @@ -366,14 +367,14 @@ kubectl create secret generic repo-launchpad \ kubectl label --local -f - argocd.argoproj.io/secret-type=repository --dry-run=client -o yaml | \ kubectl apply -f - -kubectl create secret generic repo-helm-values \ - --from-file=sshPrivateKey=key-helm-values \ +kubectl create secret generic repo-helm-prod-values \ + --from-file=sshPrivateKey=key-helm-prod-values \ --namespace=argocd --dry-run=client -o yaml | \ kubectl label --local -f - argocd.argoproj.io/secret-type=repository --dry-run=client -o yaml | \ kubectl apply -f - # Clean up keys -shred -u key-sturdy key-helm-values +shred -u key-sturdy key-helm-prod-values ``` #### Converting HTTPS to SSH @@ -390,7 +391,7 @@ If you're currently using HTTPS and want to switch to SSH: # repoURL: ssh://git@git.forteapps.net:2222/Forte/launchpad.git # 3. Update and commit -find . -name "*.yaml" -type f -exec sed -i 's|https://github.com/fortedigital/|git@github.com:fortedigital/|g' {} + +find . -name "*.yaml" -type f -exec sed -i 's|https://git.forteapps.net/Forte/|git@git.forteapps.net:Forte/|g' {} + git add . git commit -m "Switch from HTTPS to SSH for repository access" @@ -494,7 +495,7 @@ spec: See [Developer Guide](DEVELOPER-GUIDE.md#deploying-your-first-application) for detailed steps. **Quick checklist:** -- [ ] Create `helm-values/myapp/values.yaml` +- [ ] Create `helm-prod-values/myapp/values.yaml` - [ ] Create `apps/myapp.yaml` in config repo - [ ] Create SealedSecret if needed - [ ] Commit and push changes @@ -559,7 +560,7 @@ kubectl scale deployment myapp -n myapp --replicas=3 #### GitOps Scaling -Update `helm-values/myapp/values.yaml`: +Update `helm-prod-values/myapp/values.yaml`: ```yaml app: @@ -573,7 +574,7 @@ Commit and push - ArgoCD will sync. Enable Horizontal Pod Autoscaler: ```yaml -# In helm-values/myapp/values.yaml +# In helm-prod-values/myapp/values.yaml app: hpa: enabled: true @@ -622,7 +623,7 @@ kubectl rollout undo deployment myapp -n myapp #### Option 3: Change Image Tag ```bash -# Edit helm-values +# Edit helm-prod-values cd ~/dev/k8s/helm-prod-values vim myapp/values.yaml @@ -642,7 +643,7 @@ git push #### Update Resource Limits ```yaml -# In helm-values/myapp/values.yaml +# In helm-prod-values/myapp/values.yaml app: resources: requests: @@ -656,7 +657,7 @@ app: #### Enable Database ```yaml -# In helm-values/myapp/values.yaml +# In helm-prod-values/myapp/values.yaml db: enabled: true persistence: @@ -1266,7 +1267,7 @@ spec: **What Needs Backup**: - ❌ Cluster state (not backed up - recreate via GitOps) - ❌ Persistent volumes (currently not critical) -- ✅ Git repositories (GitHub provides backup) +- ✅ Git repositories (Gitea provides backup) - ⚠️ Secrets (sealed secrets in Git, unseal keys need safekeeping) ### Cluster Rebuild @@ -1561,7 +1562,7 @@ git push kubectl scale deployment myapp -n myapp --replicas=0 # Update Git -vim helm-values/myapp/values.yaml +vim helm-prod-values/myapp/values.yaml # Set replicaCount: 0 git commit -am "Scale down myapp for maintenance" git push @@ -1634,7 +1635,7 @@ echo "Remember to delete: $SECRET_FILE" - [ ] Application code repository created - [ ] Dockerfile created and tested -- [ ] GitHub Actions workflow configured +- [ ] Gitea Actions workflow configured - [ ] Helm values created in `helm-prod-values/` - [ ] ArgoCD application manifest created in `apps/` - [ ] Secrets created and sealed diff --git a/docs/REFERENCE.md b/docs/REFERENCE.md index 4732b68..a12ab22 100644 --- a/docs/REFERENCE.md +++ b/docs/REFERENCE.md @@ -190,7 +190,7 @@ spec: ### Helm Charts Repository: `forte-helm` -**URL**: `https://github.com/fortedigital/forte-helm` +**URL**: `https://git.forteapps.net/Forte/forte-helm` #### Chart: `forteapp` @@ -337,14 +337,14 @@ configmap: [] # Application ConfigMap key-value pairs --- -### Helm Values Repository: `helm-values` +### Helm Values Repository: `helm-prod-values` -**URL**: `https://github.com/fortedigital/helm-values.git` +**URL**: `https://git.forteapps.net/Forte/helm-prod-values.git` #### Structure ``` -helm-values/ +helm-prod-values/ ├── mcp10x/ │ └── values.yaml ├── musicman/ @@ -526,14 +526,14 @@ spec: # Multi-source configuration sources: - - repoURL: https://github.com/fortedigital/forte-helm + - repoURL: https://git.forteapps.net/Forte/forte-helm path: forteapp targetRevision: HEAD helm: valueFiles: - $values//values.yaml - - repoURL: git@github.com:fortedigital/helm-values.git + - repoURL: git@github.com:fortedigital/helm-prod-values.git targetRevision: HEAD ref: values