Skip to content
Terrateam

Kubernetes Deployment

Kubernetes deployment with Helm provides a production-ready, scalable solution for Terrateam Self-Hosted. This method is recommended for enterprise environments requiring high availability and automatic scaling, and supports both GitHub and GitLab.

Prerequisites

Before you begin, ensure you have:

  • Completed the Setup Wizard (see above) to generate credentials
  • Kubernetes cluster
  • Helm installed
  • kubectl configured to access your cluster

Installation Steps

  1. Source your GitHub Application settings

    Load the credentials generated by the Setup Wizard:

    Terminal window
    # From the terrateam/docker/terrat directory
    source ./dotenv

  2. Create Kubernetes secrets for GitHub App

    Create secrets for your private Terrateam GitHub Application:

    Terminal window
    kubectl create secret generic terrateam-github-app-pem \
      --from-literal=pem="$GITHUB_APP_PEM"
    

    kubectl create secret generic terrateam-github-webhook-secret \
      --from-literal=secret="$GITHUB_WEBHOOK_SECRET"
    

    kubectl create secret generic terrateam-github-app-client-secret \
      --from-literal=secret="$GITHUB_APP_CLIENT_SECRET"
    

    kubectl create secret generic terrateam-github-app-client-id \
      --from-literal=id="$GITHUB_APP_CLIENT_ID"
    

    kubectl create secret generic terrateam-github-app-id \
      --from-literal=id="$GITHUB_APP_ID"

  3. Create database password secret

    Terminal window
    kubectl create secret generic terrateam-db-password \
      --from-literal=password="STRONG_PASSWORD_HERE"

  4. Add Terrateam Helm repository

    Terminal window
    helm repo add terrateamio https://terrateamio.github.io/helm-charts/
    helm repo update

  5. Choose your deployment configuration

    Select one of the deployment options below based on your infrastructure.

Deployment Options

GKE with HTTPS Load Balancer

For Google Kubernetes Engine with managed SSL certificates:

  1. Create a global static IP address:

    Terminal window
    gcloud compute addresses create terrateam-static-ip --global

  2. Get the IP address:

    Terminal window
    gcloud compute addresses describe terrateam-static-ip --global

  3. Configure DNS

    Add the static IP to your DNS zone as terrateam.example.com

  4. Install with Helm

    Choose the appropriate command for your platform below.

Terminal window
helm install terrateam terrateamio/terrateam \
  --set terrateam.config.fqdn="terrateam.example.com" \
  --set terrateam.config.vcs="github" \
  --set terrateam.config.github.appUrl="$GITHUB_APP_URL" \
  --set terrateam.config.uiBase="https://terrateam.example.com" \
  --set ingress.certificate.enabled="true" \
  --set ingress.enabled="true" \
  --set ingress.className="gce" \
  --set ingress.annotations."networking\.gke\.io/managed-certificates"="terrateam-ingress-certificate" \
  --set ingress.annotations."kubernetes\.io/ingress\.global-static-ip-name"="terrateam-static-ip" \
  --set-string ingress.annotations."kubernetes\.io/ingress\.allow-http"="false"

Without Ingress

For clusters without ingress controllers:

Terminal window
helm install terrateam terrateamio/terrateam \
  --set terrateam.config.fqdn="terrateam.example.com" \
  --set terrateam.config.github.appUrl="$GITHUB_APP_URL" \
  --set terrateam.config.uiBase="https://terrateam.example.com"

You can later expose the terrateam-server service using:

Configure Webhook URLs

For GitHub, you need to configure the webhook URL in your GitHub App settings:

  1. Navigate to your GitHub App settings page (find the URL in your .env file)
  2. Go to the “General” tab
  3. In the “Webhook” section, set the URL to: https://terrateam.example.com/api/github/v1/events
  4. Ensure the webhook secret matches the one you configured during setup
  5. Save your changes

Enable Terrateam UI Access

To enable the Terrateam web UI for GitHub:

  1. Navigate to your GitHub App settings (e.g., https://github.com/apps/your-terrateam-app)
  2. Click on “App settings” on the right side under the Install button
  3. Check the box “Request user authorization (OAuth) during installation”
  4. Set the callback URL to: https://terrateam.example.com/api/github/v1/callback
  5. Save your changes

Getting Started Wizard

Once you’ve enabled UI access, the next step is to complete the Getting Started Wizard:

  1. Access the Terrateam UI

    • Navigate to: https://terrateam.example.com
    • Log in with your GitHub or GitLab account

  2. Complete the Getting Started Wizard

    The wizard will guide you through:

    • Repository/Project Selection: Choose which repositories (GitHub) or projects (GitLab) to enable for Terrateam
    • Cloud Provider Configuration: Set up credentials for AWS, GCP, Azure, or other cloud providers
    • Workflow Setup: Configure your first Terraform workflows and apply requirements
    • Team Permissions: Set up role-based access control if needed

  3. Verify Your Setup

    • Create a test pull request or merge request
    • Confirm Terrateam responds with a plan
    • Apply your first change

Production Management

This section covers essential tasks for managing your Terrateam deployment in production, including scaling, monitoring, maintenance, and troubleshooting.

Scaling and High Availability

Horizontal Scaling

Scale the number of Terrateam server replicas:

Terminal window
helm upgrade terrateam terrateamio/terrateam \
  --set server.replicas=3

Database High Availability

For production workloads, consider:

  • External managed PostgreSQL (AWS RDS, Google Cloud SQL, Azure Database)
  • PostgreSQL cluster with automatic failover
  • Regular database backups

Monitoring and Logging

Health Checks

Terrateam provides health check endpoints:

  • /health - Overall application health
  • /metrics - Prometheus metrics (if enabled)

Maintenance

Updates

Update to the latest Terrateam version:

Terminal window
helm repo update
helm upgrade terrateam terrateamio/terrateam

Rolling Restarts

Perform rolling restart without downtime:

Terminal window
kubectl rollout restart deployment/terrateam-server