Helm Deployment

Deploy Governance Studio to a Kubernetes cluster.

Overview

This guide covers deploying the Governance Platform to a Kubernetes cluster after:

Preparing values.yaml and secrets.yaml files
Provisioning all external cloud resources (storage, key management, authentication)
Setting up the Kubernetes cluster with required components

Prerequisites

Before deploying, ensure the following are available:

Kubernetes 1.21+ cluster
Helm 3.8+ (installation guide)
kubectl configured to access the cluster
Persistent volume provisioner available in the cluster
NGINX Ingress Controller installed (installation guide)
cert-manager installed (installation guide)
Certificate Issuer configured (e.g. Let’s Encrypt ClusterIssuer) (configuration guide)
Domain name with ability to configure DNS A records
Completed values.yaml and secrets.yaml files from previous setup steps

Step 1: Create Kubernetes Namespace

Create a dedicated namespace for the Governance Platform:

# Create namespace
kubectl create namespace governance

# Set as default context (optional)
kubectl config set-context --current --namespace=governance

Step 2: Deploy with Helm

Authenticate to GitHub Container Registry

helm registry login ghcr.io

Enter GitHub username and personal access token when prompted.

Deploy the Platform

Replace <chart-version> with the governance-platform chart version recorded in the release manifest for the platform version you are deploying.

helm upgrade --install governance-platform \
  oci://ghcr.io/eqtylab/charts/governance-platform \
  --version <chart-version> \
  --namespace governance \
  --create-namespace \
  --values values.yaml \
  --values secrets.yaml \
  --wait \
  --timeout 10m

Always pass --version. Without it Helm installs whichever chart version is newest in the registry, which may not be the version your values, images, and release manifest were validated against.

Note: Run the same command to upgrade after changing values or deploying a new version, updating --version to the target release.

Monitor Deployment

kubectl get pods -n governance -w
helm status governance-platform -n governance

Verify Deployment

Check Pods and Services

kubectl get pods -n governance
kubectl get svc -n governance
kubectl get ingress -n governance

All pods should show Running status and Ready state.

Verify TLS Certificates

kubectl get certificates -n governance
kubectl describe certificate <cert-name> -n governance

If certificates are not issuing:

Check ClusterIssuer status: kubectl describe clusterissuer letsencrypt-prod
Check certificate events: kubectl describe certificate <cert-name> -n governance
Check cert-manager logs: kubectl logs -n ingress-nginx -l app=cert-manager

Configure DNS

Get the external IP of the ingress controller:

kubectl get svc -n ingress-nginx

Create a DNS A record pointing the configured domain to the LoadBalancer’s external IP address. The domain should match what was configured in values.yaml for the ingress hosts.

Troubleshooting

If pods fail to start, check the logs:

kubectl get pods -n governance
kubectl logs <pod-name> -n governance
kubectl describe pod <pod-name> -n governance

Common issues:

ImagePullBackOff: Check image tags in values.yaml and registry access
CrashLoopBackOff: Check pod logs for application errors
Pending PVCs: Verify persistent volume provisioner is available
Database connection errors: Verify database credentials in secrets.yaml

Access the Platform

Once DNS propagates, access Governance Studio at the configured domain. The platform will redirect to the configured identity provider for authentication.

Uninstalling

To completely remove the platform:

# Uninstall the Helm release
helm uninstall governance-platform -n governance

# Delete the namespace (optional)
kubectl delete namespace governance

Warning: This will delete all data stored in Kubernetes. External resources (S3 buckets, KMS keys, Entra apps) must be deleted separately.

Next Steps

Review the Chart Values documentation for customization options
Set up monitoring and alerting
Configure backups for the PostgreSQL database
Review security best practices for your deployment