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
-
Source your GitHub Application settings
Load the credentials generated by the Setup Wizard:
Terminal window # From the terrateam/docker/terrat directorysource ./dotenv -
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" -
Create database password secret
Terminal window kubectl create secret generic terrateam-db-password \--from-literal=password="STRONG_PASSWORD_HERE" -
Add Terrateam Helm repository
Terminal window helm repo add terrateamio https://terrateamio.github.io/helm-charts/helm repo update -
Choose your deployment configuration
Select one of the deployment options below based on your infrastructure.
-
Source your GitLab configuration
Load the credentials generated by the Setup Wizard:
Terminal window # From the terrateam/docker/terrat directorysource ./dotenv -
Create Kubernetes secrets for GitLab
Create secrets for your GitLab configuration:
Terminal window kubectl create secret generic terrateam-gitlab-app-id \--from-literal=id="$GITLAB_APP_ID"kubectl create secret generic terrateam-gitlab-app-secret \--from-literal=secret="$GITLAB_APP_SECRET"kubectl create secret generic terrateam-gitlab-access-token \--from-literal=token="$GITLAB_ACCESS_TOKEN" -
Create database password secret
Terminal window kubectl create secret generic terrateam-db-password \--from-literal=password="STRONG_PASSWORD_HERE" -
Add Terrateam Helm repository
Terminal window helm repo add terrateamio https://terrateamio.github.io/helm-charts/helm repo update -
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:
-
Create a global static IP address:
Terminal window gcloud compute addresses create terrateam-static-ip --global -
Get the IP address:
Terminal window gcloud compute addresses describe terrateam-static-ip --global -
Configure DNS
Add the static IP to your DNS zone as
terrateam.example.com
-
Install with Helm
Choose the appropriate command for your platform below.
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.annotations."networking\.gke\.io\/managed-certificates"="terrateam-ingress-certificate" \ --set ingress.annotations."kubernetes\.io\/ingress\.global-static-ip-name"="terrateam-static-ip" \ --set ingress.annotations."kubernetes\.io\/ingress\.class"="gce" \ --set-string ingress.annotations."kubernetes\.io\/ingress\.allow-http"="false"
helm install terrateam terrateamio/terrateam \ --set terrateam.config.fqdn="terrateam.example.com" \ --set terrateam.config.vcs="github" \ --set terrateam.config.github.apiBaseUrl="https://api.github.example.com" \ --set terrateam.config.github.webBaseUrl="https://github.example.com" \ --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.annotations."networking\.gke\.io\/managed-certificates"="terrateam-ingress-certificate" \ --set ingress.annotations."kubernetes\.io\/ingress\.global-static-ip-name"="terrateam-static-ip" \ --set ingress.annotations."kubernetes\.io\/ingress\.class"="gce" \ --set-string ingress.annotations."kubernetes\.io\/ingress\.allow-http"="false"
helm install terrateam terrateamio/terrateam \ --set terrateam.config.fqdn="terrateam.example.com" \ --set terrateam.config.github.enabled=false \ --set terrateam.config.gitlab.enabled=true \ --set terrateam.config.uiBase="https://terrateam.example.com" \ --set ingress.certificate.enabled="true" \ --set ingress.enabled="true" \ --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 ingress.annotations."kubernetes\.io\/ingress\.class"="gce" \ --set-string ingress.annotations."kubernetes\.io\/ingress\.allow-http"="false"
helm install terrateam terrateamio/terrateam \ --set terrateam.config.fqdn="terrateam.example.com" \ --set terrateam.config.github.enabled=false \ --set terrateam.config.gitlab.enabled=true \ --set terrateam.config.gitlab.apiBaseUrl="https://gitlab.example.com/api" \ --set terrateam.config.gitlab.webBaseUrl="https://gitlab.example.com" \ --set terrateam.config.uiBase="https://terrateam.example.com" \ --set ingress.certificate.enabled="true" \ --set ingress.enabled="true" \ --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 ingress.annotations."kubernetes\.io\/ingress\.class"="gce" \ --set-string ingress.annotations."kubernetes\.io\/ingress\.allow-http"="false"
Without Ingress
For clusters without ingress controllers:
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"
helm install terrateam terrateamio/terrateam \ --set terrateam.config.fqdn="terrateam.example.com" \ --set terrateam.config.github.apiBaseUrl="https://api.github.example.com" \ --set terrateam.config.github.webBaseUrl="https://github.example.com" \ --set terrateam.config.github.appUrl="$GITHUB_APP_URL" \ --set terrateam.config.uiBase="https://terrateam.example.com"
helm install terrateam terrateamio/terrateam \ --set terrateam.config.fqdn="terrateam.example.com" \ --set terrateam.config.github.enabled=false \ --set terrateam.config.gitlab.enabled=true \ --set terrateam.config.uiBase="https://terrateam.example.com"
helm install terrateam terrateamio/terrateam \ --set terrateam.config.fqdn="terrateam.example.com" \ --set terrateam.config.github.enabled=false \ --set terrateam.config.gitlab.enabled=true \ --set terrateam.config.gitlab.apiBaseUrl="https://gitlab.example.com/api" \ --set terrateam.config.gitlab.webBaseUrl="https://gitlab.example.com" \ --set terrateam.config.uiBase="https://terrateam.example.com"
You can later expose the terrateam-server
service using:
- NGINX Ingress Controller
- cert-manager for SSL certificates
Configure Webhook URLs
For GitHub, you need to configure the webhook URL in your GitHub App settings:
- Navigate to your GitHub App settings page
- Go to the “General” tab
- In the “Webhook” section, set the URL to:
https://terrateam.example.com/api/github/v1/events
- Ensure the webhook secret matches the one you configured during setup
- Save your changes
For GitLab, you’ll need to configure webhooks in your GitLab projects:
- Navigate to your GitLab project settings
- Go to Settings → Webhooks
- Add webhook URL:
https://terrateam.example.com/api/gitlab/v1/events
- Select the following events:
- Push events
- Merge request events
- Comments
- Pipeline events
Enable Terrateam UI Access
To enable the Terrateam web UI for GitHub:
- Navigate to your GitHub App settings (e.g.,
https://github.com/apps/your-terrateam-app
) - Click on “App settings” on the right side under the Install button
- Check the box “Request user authorization (OAuth) during installation”
- Set the callback URL to:
https://terrateam.example.com/api/github/v1/callback
- Save your changes
To access the Terrateam web UI for GitLab:
- Ensure your GitLab Personal Access Token is configured with the required scopes
- The UI access is already enabled through the OAuth configuration during setup
Getting Started Wizard
Once you’ve enabled UI access, the next step is to complete the Getting Started Wizard:
-
Access the Terrateam UI
- Navigate to:
https://terrateam.example.com
- Log in with your GitHub or GitLab account
- Navigate to:
-
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
-
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:
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:
helm repo updatehelm upgrade terrateam terrateamio/terrateam
Rolling Restarts
Perform rolling restart without downtime:
kubectl rollout restart deployment/terrateam-server