tools-only 🚢 Deploying ContextForge Stack with Argo CD
This guide shows how to operate the ContextForge Stack with a Git-Ops workflow powered by Argo CD. Once wired up, every commit to the repository becomes an automatic deployment (or rollback) to your Kubernetes cluster.
🌳 Git source of truth:
https://github.com/IBM/mcp-context-forge
- App manifests:
deployment/k8s/(Kustomize-ready)- Helm chart (optional):
charts/mcp-stack
📋 Prerequisites
| Requirement | Notes |
|---|---|
| Kubernetes ≥ 1.23 | Local (Minikube/kind) or managed (EKS, AKS, GKE, etc.) |
| Argo CD ≥ 2.7 | Server & CLI (this guide installs server into the cluster) |
| kubectl | Configured to talk to the target cluster |
| Git access | The cluster must be able to pull the repo (public or deploy-key) |
🛠 Step 1 - Install Argo CD (once per cluster)
# Namespace + core components
kubectl create namespace argocd
kubectl apply -n argocd \
-f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
# Wait for the server component
kubectl -n argocd rollout status deploy/argocd-server
Install the CLI
# macOS
brew install argocd
# Linux (single-binary)
curl -sSL -o /tmp/argocd \
https://github.com/argoproj/argo-cd/releases/latest/download/argocd-linux-amd64
sudo install -m 555 /tmp/argocd /usr/local/bin/argocd
Verify:
argocd version --client
🔐 Step 2 - Initial Login
Forward the API/UI to your workstation (leave running):
kubectl -n argocd port-forward svc/argocd-server 8083:443
Fetch the one-time admin password and log in:
PASS="$(kubectl -n argocd get secret argocd-initial-admin-secret \
-o jsonpath='{.data.password}' | base64 -d)"
argocd login localhost:8083 \
--username admin --password "$PASS" --insecure
Open the web UI → https://localhost:8083 (credentials above).
🚀 Step 3 - Bootstrap the Application
Create an Argo CD Application that tracks the deployment/k8s/ folder from the main branch:
APP=mcp-gateway
REPO=https://github.com/IBM/mcp-context-forge.git
argocd app create "$APP" \
--repo "$REPO" \
--path deployment/k8s \
--dest-server https://kubernetes.default.svc \
--dest-namespace default \
--sync-policy automated \
--revision main
Trigger the first sync:
argocd app sync "$APP"
Argo CD will apply all manifests and keep them in the Synced 🌿 / Healthy 💚 state.
✅ Step 4 - Verify Deployment
kubectl get pods,svc,ingress
argocd app list
argocd app get mcp-gateway
If using the sample Ingress:
curl http://gateway.local/health
Otherwise, port-forward:
kubectl port-forward svc/mcp-context-forge 8080:80 &
curl http://localhost:8080/health
🔄 Day-2 Operations
Sync after a new commit
argocd app sync mcp-gateway
View diff before syncing
argocd app diff mcp-gateway
Roll back to a previous revision
argocd app history mcp-gateway
argocd app rollback mcp-gateway <REVISION>
Disable / enable auto-sync
# Pause auto-sync
argocd app set mcp-gateway --sync-policy none
# Re-enable
argocd app set mcp-gateway --sync-policy automated
🧹 Uninstall
# Delete the application (leaves cluster objects intact)
argocd app delete mcp-gateway --yes
# Remove Argo CD completely
kubectl delete ns argocd
🧰 Makefile Shortcuts
The repository ships with ready-made targets:
| Target | Action |
|---|---|
make argocd-install |
Installs Argo CD server into the current cluster |
make argocd-forward |
Port-forwards UI/API on http://localhost:8083 |
make argocd-app-bootstrap |
Creates & auto-syncs the mcp-gateway application |
make argocd-app-sync |
Forces a manual sync |
Run make help to list them all.
🧯 Troubleshooting
| Symptom | Fix |
|---|---|
ImagePullBackOff |
Check image name / pull secret & that the repo is public or credentials are configured in Argo CD |
SyncFailed |
argocd app logs mcp-gateway for details; often due to immutable fields |
| Web UI 404 | Ensure argocd-forward is still running, or expose via Ingress/LoadBalancer |
| RBAC denied | Argo CD needs ClusterRoleBinding for non-default namespaces - see docs |
📚 Further Reading
- Argo CD Docs - https://argo-cd.readthedocs.io
- GitOps Pattern - https://www.weave.works/technologies/gitops/
- Kustomize - https://kubectl.docs.kubernetes.io/references/kustomize/
- Helm + Argo CD - https://argo-cd.readthedocs.io/en/stable/user-guide/helm/