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 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
       
      
       
       
      \
     
    
    
     
       
      --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
       
      
       
       
      -n
       
      governance

If certificates are not issuing:

Check ClusterIssuer status: kubectl describe clusterissuer letsencrypt-prod
Check certificate events: kubectl describe certificate -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
       
      
       
       
      -n
       
      governance
     
    
    
     
      kubectl
       
      describe
       
      pod
       
      
       
       
      -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