GitOps-Based Installation

Goal

Deploy all Keymate platform components on a Kubernetes cluster using ArgoCD for automated, Git-driven delivery. At the end of this guide, ArgoCD manages the complete Keymate platform lifecycle — deploying components in the correct dependency order, detecting drift, and keeping the cluster synchronized with the declared configuration in Git.

Audience

Platform engineers and operators who use or plan to adopt ArgoCD for GitOps-based infrastructure and application delivery.

Prerequisites

• A running Kubernetes cluster
• ArgoCD installed and accessible (see the ArgoCD documentation for installation)
• A Git repository for storing Keymate platform configuration
• kubectl configured with administrative access to the target cluster
• DNS records configured for platform endpoints
• TLS certificates provisioned (or cert-manager configured for automated provisioning)
• Database credentials and connection details prepared
• Completed Pre-Deployment Checklist

Before You Start

• ArgoCD must be running. This guide does not cover ArgoCD installation. Verify ArgoCD is healthy by accessing the ArgoCD UI or running argocd app list.
• Prepare the GitOps repository. Create a Git repository (or a directory within an existing one) to hold the Keymate platform configuration. This repository becomes the single source of truth for your deployment.
• Prepare credentials. Gather database passwords, TLS certificates, SMTP configuration, and any external service credentials. Store these as Kubernetes Secrets that the platform configuration references.

warning

The GitOps repository is the source of truth. Once ArgoCD manages the platform, avoid making manual changes to Keymate resources in the cluster — ArgoCD detects these as drift and restores the declared state.

How GitOps Deployment Differs from Helm

Aspect	Helm-Based	GitOps-Based
Installation method	Run helm install commands manually	Apply a root application, ArgoCD handles the rest
Dependency ordering	You manage the sequence	ArgoCD manages the sequence automatically
Drift detection	None — manual verification	Continuous — ArgoCD alerts on divergence
Rollback	helm rollback per release	Git revert, ArgoCD applies automatically
Audit trail	Helm release history	Full Git commit history
Multi-environment	Separate value files per environment	Directory or branch-based separation in Git

Steps

1. Prepare the GitOps repository structure

Create a repository structure that separates platform configuration by environment.

keymate-gitops/
├── environments/
│   ├── dev/
│   │   └── values/          # Dev environment overrides
│   ├── staging/
│   │   └── values/          # Staging environment overrides
│   └── production/
│       └── values/          # Production environment overrides
└── root-application.yaml    # ArgoCD entry point

tip

Start with a single environment (dev) and add staging and production after validating the deployment workflow.

2. Register the Git repository in ArgoCD

Register your GitOps repository so ArgoCD can access it. Omit the --password flag to enter the access token interactively — this prevents the token from being stored in your shell history.

argocd repo add <GIT_REPOSITORY_URL> \
  --username <USERNAME>

ArgoCD prompts for the password interactively. Alternatively, use a Kubernetes Secret-based repository configuration to avoid CLI credential handling entirely.

Verify the connection:

argocd repo list

3. Create the ArgoCD project

Create an ArgoCD project to scope permissions and resource access for the Keymate deployment.

kubectl apply -f argocd-project.yaml

The project defines which namespaces, cluster resources, and repositories the Keymate applications can use.

4. Deploy the root application

The root application is the single entry point for the entire Keymate deployment. ArgoCD uses it to discover and deploy all platform components.

kubectl apply -f root-application.yaml

Once applied, ArgoCD:

1. Reads the root application definition
2. Discovers all child applications (platform components)
3. Deploys components in the correct dependency order
4. Reports synchronization status for each component

5. Monitor the deployment progress

Track the deployment through the ArgoCD UI or CLI.

argocd app list

Each component progresses through these states:

State	Meaning
OutOfSync	ArgoCD detected the change, sync not yet started
Syncing	Deployment in progress
Synced	Cluster matches the declared state in Git
Healthy	All pods running and passing health checks
Degraded	One or more pods are unhealthy

Wait for all applications to reach Synced and Healthy status before proceeding.

6. Verify the deployment

Confirm that all platform components are running.

# Check ArgoCD application health
argocd app list

# Check pods across all namespaces
kubectl get pods -A | grep keymate

All applications should show Synced and Healthy. All pods should show Running status with all containers ready.

7. Configure environment-specific overrides

Customize the deployment for your environment by modifying the values files in the GitOps repository.

# Edit environment-specific values
vi environments/dev/values/identity.yaml

# Commit and push
git add .
git commit -m "configure identity provider for dev environment"
git push

ArgoCD detects the commit and automatically applies the changes to the cluster.

Validation Scenario

Scenario

Verify that the Keymate platform is fully deployed and managed by ArgoCD after completing the installation.

Expected Result

• All ArgoCD applications show Synced and Healthy status
• The identity provider login page loads through the configured domain
• The API gateway responds to health check requests
• The observability dashboard loads and receives telemetry data
• Making a configuration change in Git triggers an automatic sync

How to Verify

• ArgoCD status: argocd app list shows all applications Synced and Healthy
• Drift test: Manually change a resource in the cluster, verify ArgoCD detects the drift within its reconciliation interval
• Git-driven change: Commit a configuration change to Git, verify ArgoCD applies it to the cluster automatically
• Health endpoints: Access the platform health endpoint through the configured ingress domain

Troubleshooting

• Application stuck in OutOfSync. Check the ArgoCD application details for sync errors: argocd app get <app-name>. Common causes: missing Secrets, resource quota limits, or CRD dependencies.
• Sync fails with dependency errors. Components may attempt to sync before their dependencies are ready. ArgoCD retries automatically — wait for the dependency to become healthy, then the dependent application syncs on the next cycle.
• Repository connection failed. Verify the Git repository URL and credentials: argocd repo list. Ensure network access from the ArgoCD server to the Git host.
• Pods in CrashLoopBackOff. Check pod logs: kubectl logs <pod-name> -n <namespace>. Common causes include missing database credentials, unreachable data services, or insufficient resources.

tip

Use argocd app diff <app-name> to see the exact differences between the Git-declared state and the current cluster state. This helps diagnose sync issues without reading through full manifests.

Next Steps

After a successful installation:

• Tenant Onboarding — Add your first Tenant and configure initial access
• Multi-Environment Management — Set up staging and production environments
• Customization Overview — Learn about tenant-level and environment-level configuration options
• Observability Overview — Set up dashboards, alerts, and telemetry export

Related Docs

GitOps with ArgoCD

Deployment model overview and when to choose GitOps

Pre-Deployment Checklist

Verify readiness before starting installation

Helm-Based Installation

Alternative: deploy with direct Helm commands

Platform Components

Full component list and dependency order