Helm-Based Installation
Helm-based installation is the primary packaging direction for Keymate. This guide describes the general installation approach. The team is finalizing specific chart names, repository locations, and values documentation as part of the productized Helm delivery.
Goal
Deploy all Keymate platform components on a Kubernetes cluster using Helm charts. At the end of this guide, you have a running Keymate platform with identity services, authorization engine, API gateway, and observability stack — all installed and verified without ArgoCD or any GitOps tooling.
Audience
Platform engineers responsible for deploying and maintaining Keymate in their Kubernetes infrastructure.
Prerequisites
- A running Kubernetes cluster (v1.28 or later recommended)
- Helm v3.12 or later installed on your workstation
kubectlconfigured with administrative access to the target cluster- DNS records configured for platform endpoints
- TLS certificates provisioned (or cert-manager installed for automated provisioning)
- Database credentials and connection details prepared
- Completed Pre-Deployment Checklist
Before You Start
- Verify cluster capacity. Keymate deploys multiple components across infrastructure, data, application, and observability layers. Ensure your cluster has sufficient CPU, memory, and storage. Check the Pre-Deployment Checklist for minimum resource requirements.
- Plan your namespaces. Keymate organizes components into logical namespaces by function. Decide whether to use the default namespace layout or customize it.
- Prepare credentials. Gather database passwords, TLS certificates, SMTP configuration, and any external service credentials before starting. You provide these as Kubernetes Secrets or Helm values during installation.
Install components in the documented dependency order. Skipping layers or installing out of sequence causes startup failures because later components depend on services from earlier layers.
Installation Overview
Keymate follows a layered installation model. Each layer must be healthy before proceeding to the next.
| Layer | What it includes | Why this order |
|---|---|---|
| Infrastructure | Service mesh, certificate management, operators | Provides networking, TLS, and operator CRDs required by all other components |
| Data | Databases, caches, message brokers | Stores persistent state consumed by application services |
| Application | Identity provider, authorization engine, API gateway, platform services | Core Keymate functionality that requires infrastructure and data layers |
| Observability | Telemetry collection, dashboards, alerting | Monitors all previously deployed components |
Steps
1. Add the Keymate Helm repository
Add the Keymate chart repository to your Helm configuration.
helm repo add keymate <CHART_REPOSITORY_URL>
helm repo update
The chart repository URL and access credentials are provided during onboarding. Contact your Keymate representative if you do not have repository access.
2. Create namespaces
Create the namespaces required by platform components.
kubectl create namespace keymate-system
kubectl create namespace keymate-data
kubectl create namespace keymate-gateway
kubectl create namespace keymate-observability
3. Install the infrastructure layer
Install the infrastructure components first: service mesh and optionally certificate management.
# Install service mesh components (required)
helm install service-mesh keymate/service-mesh \
-n keymate-system \
-f values-service-mesh.yaml
# Install cert-manager for TLS automation (optional — skip if you manage TLS externally)
helm install cert-manager keymate/cert-manager \
-n keymate-system \
-f values-cert-manager.yaml
Wait for all infrastructure components to reach a healthy state before proceeding.
kubectl get pods -n keymate-system
All pods should show Running or Completed status.
4. Install the data layer
Install databases, caches, and message brokers.
# Install database operator and instances
helm install database keymate/database \
-n keymate-data \
-f values-database.yaml
# Install cache
helm install cache keymate/cache \
-n keymate-data \
-f values-cache.yaml
Wait for data services to become ready and accept connections.
kubectl get pods -n keymate-data
5. Install the application layer
Install the Keymate core services: identity provider, authorization engine, API gateway, and platform services.
# Install identity provider
helm install identity keymate/identity \
-n keymate-system \
-f values-identity.yaml
# Install authorization engine
helm install authorization keymate/authorization \
-n keymate-system \
-f values-authorization.yaml
# Install API gateway
helm install gateway keymate/gateway \
-n keymate-gateway \
-f values-gateway.yaml
# Install platform services
helm install platform keymate/platform-services \
-n keymate-system \
-f values-platform.yaml
6. Install the observability layer (recommended)
Install telemetry collection, dashboards, and alerting. We recommend this layer but it is not strictly required — you can skip it if you use external monitoring tools and configure telemetry export separately through the OpenTelemetry-first model.
helm install observability keymate/observability \
-n keymate-observability \
-f values-observability.yaml
7. Configure ingress and DNS
Configure external access to the platform services.
helm install ingress keymate/ingress \
-n keymate-gateway \
-f values-ingress.yaml
Verify that DNS records resolve to the ingress endpoints and TLS certificates are valid.
8. Verify the deployment
Run a comprehensive health check across all layers.
# Check all namespaces
kubectl get pods -n keymate-system
kubectl get pods -n keymate-data
kubectl get pods -n keymate-gateway
kubectl get pods -n keymate-observability
All pods should show Running status with all containers ready.
Validation Scenario
Scenario
Verify that the Keymate platform is fully operational after installation by checking service health across all layers.
Expected Result
- All pods are running and healthy across all namespaces
- 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
How to Verify
- Health endpoints: Access the platform health endpoint through the configured ingress domain
- Identity provider: Navigate to the identity provider admin console URL and verify the login page loads
- API gateway: Send a test request through the API gateway and confirm a response
- Observability: Access the observability dashboard and verify that metrics, logs, and traces are being collected
Troubleshooting
- Pods stuck in Pending state. Check cluster resource capacity. Keymate components require sufficient CPU and memory. Run
kubectl describe pod <pod-name>to see scheduling constraints. - Database connection failures. Verify database credentials in the Helm values. Ensure the database is accessible from the cluster network and accepting connections.
- TLS certificate errors. Confirm that cert-manager is running and DNS records are correctly configured. Check certificate status with
kubectl get certificates -A. - Components failing to start. Verify that earlier layers are healthy before troubleshooting later layers. Application services fail when infrastructure or data services are not ready.
If a component fails to start, check the dependency order first. The most common installation issue is proceeding to a later layer before an earlier layer is fully healthy.
Next Steps
After a successful installation:
- Tenant Onboarding — Add your first Tenant and configure initial access
- Customization Overview — Learn about environment and tenant-level configuration options
- Deployment Best Practices — Review production readiness recommendations
- Observability Overview — Set up dashboards, alerts, and telemetry export