CLI Reference¶

MANA does not ship a standalone command-line client. Day-to-day operations use four tools that the repository already provides or assumes: make (shortcuts), scripts/deploy.sh (end-to-end deployment), docker compose (local stack) and curl/kubectl (talking to the running system). This page documents each.

The Makefile references seven helper scripts, but only scripts/deploy.sh is present in the repository. Targets that need a missing script fail with No such file or directory. They are marked missing script below. Either add the script or run the equivalent manual steps shown.

Run make or make help at any time to list targets with descriptions.

Makefile¶

Variables can be overridden per invocation, for example make deploy-app NAMESPACE=staging APP_VERSION=1.2.3.

Setup¶

Manual equivalent of setup-cluster:

kind create cluster --name self-healing-cicd      # or: minikube start
kubectl create namespace production        # namespaces are also created by Terraform
kubectl create namespace orchestrator

Build¶

Test and quality¶

Deploy¶

scripts/deploy.sh also runs Terraform unless you pass --skip-infra, so make deploy applies Terraform twice. Use make deploy-app alone (it still runs Terraform once) or call the script with --skip-infra.

Access and logs¶

Status and utilities¶

Cleanup¶

clean, clean-all and reset delete namespaces and run terraform destroy -auto-approve with no confirmation. Never run them against a cluster you care about.

Local stack and extras¶

To build and preview this documentation site instead, use MkDocs directly:

pip install mkdocs mkdocs-shadcn pymdown-extensions
mkdocs serve        # http://127.0.0.1:8000
mkdocs build --strict

scripts/deploy.sh¶

Orchestrates a full deployment: prerequisite check, Terraform, image build and load, Redis, orchestrator, sample app, verification, monitoring and smoke tests.

./scripts/deploy.sh [--namespace NAME] [--version TAG] [--skip-infra] [--skip-monitoring]

Environment: NAMESPACE, APP_VERSION, DEPLOY_TIMEOUT (seconds per kubectl wait, default 600).

Steps, in order:

1. Verify kubectl, docker, helm and terraform are installed and the cluster is reachable.
2. terraform init, plan -out=tfplan, apply (unless --skip-infra).
3. Build sample-app:<version> and orchestrator:latest; load them into Minikube or Kind if detected.
4. Install a Bitnami Redis with Helm into the orchestrator namespace.
5. kubectl apply -f orchestrator/k8s/ and wait for the orchestrator Deployment.
6. Temporarily rewrite the image tag in sample-app/k8s/deployment.yaml, apply it, wait, and restore the file.
7. Verify pods, service and /health from inside a pod.
8. terraform apply -var="enable_monitoring=true" and wait for Grafana (unless --skip-monitoring).
9. Port-forward and smoke-test /health, / and /api/data; print access information.

Exit code is 0 on success and 1 on any error (set -e plus explicit checks).

!!! note "Things to know" - orchestrator/k8s/deployment.yaml expects a Secret named github-token and a GITHUB_REPO you have edited; create the Secret before running the script or the orchestrator pod will not start. - Step 4 installs Redis through Helm (service redis-master), while orchestrator/k8s/redis.yaml also deploys redis-service, which is the host the orchestrator is configured to use. - Terraform and the manifests in step 5/6 can both manage the same Deployments. Pick one source of truth to avoid drift.

terraform/validate-terraform.sh¶

Checks tool availability (Terraform, kubectl, optional cluster access) and validates the Terraform root module and sub-modules, printing a pass/fail/warning summary.

cd terraform && ./validate-terraform.sh

Typical manual Terraform workflow:

cd terraform
terraform init
terraform fmt -check -recursive
terraform validate
terraform plan -var="environment=local" -var="enable_staging=false"
terraform apply
terraform destroy

Docker Compose¶

docker compose up -d                    # redis, sample-app, orchestrator, prometheus, grafana, loki, promtail
docker compose ps
docker compose logs -f orchestrator
docker compose up -d --build sample-app # rebuild one service
docker compose down -v                  # stop and delete volumes

Operating a Running System¶

Replace $MANA with your orchestrator URL (see the API Reference).

Orchestrator¶

# Is it healthy, and are Redis/Kubernetes reachable?
curl -s $MANA/health | jq

# Which settings are active?
curl -s $MANA/config | jq

# What happened to a deployment?
curl -s $MANA/deployment/<deployment-id> | jq
curl -s "$MANA/deployments/recent?namespace=production&limit=20" | jq

# Manual rollback through MANA (audited, verified)
curl -s -X POST $MANA/rollback -H 'Content-Type: application/json' \
  -d '{"namespace":"production","deployment_name":"sample-app","target_version":"<tag>"}'

# Simulate a failure event
curl -s -X POST $MANA/webhook/deployment -H 'Content-Type: application/json' \
  -d '{"deployment_id":"demo-1","namespace":"production","app_name":"sample-app","version":"v2","status":"failed","failure_type":"health_check_failure","metadata":{"workflow_run_id":"1"}}'

Logs and audit trail¶

kubectl logs -n orchestrator -l app=orchestrator --tail=200 -f
kubectl logs -n orchestrator -l app=orchestrator | grep "AUDIT:"
kubectl logs -n orchestrator -l app=orchestrator | grep "<deployment-id>"

Redis inspection¶

kubectl exec -n orchestrator deploy/redis -- redis-cli keys 'deployment:*'
kubectl exec -n orchestrator deploy/redis -- redis-cli get 'last_successful:production:sample-app'
kubectl exec -n orchestrator deploy/redis -- redis-cli ttl 'deployment:<deployment-id>'

Sample app¶

kubectl get pods -n production -l app=sample-app -w
kubectl rollout history deployment/sample-app -n production
kubectl set env deployment/sample-app FAILURE_RATE=0.5 -n staging
kubectl set image deployment/sample-app sample-app=ghcr.io/<owner>/mana/sample-app:<tag> -n staging

Monitoring¶

make port-forward-prometheus   # then open http://localhost:9090/targets
make port-forward-grafana      # http://localhost:3000 (admin / admin123 by default)
curl -s http://localhost:9090/api/v1/query --data-urlencode 'query=sum(rate(deployments_total[5m])) by (status)' | jq

Exit Codes and Output Conventions¶

Scripts print [INFO], [SUCCESS], [WARNING] and [ERROR] prefixes with ANSI colours; pipe through sed 's/\x1b\[[0-9;]*m//g' if you need plain text in CI logs.