Galasa Helm Charts

Helm charts for deploying Galasa components to Kubernetes, including the complete Galasa Ecosystem.

⚠️ Migration notice — Galasa v1.0.0 image registry change

From Galasa v1.0.0, Docker images are published to icr.io/galasa (public, no credentials required). Images will continue to be mirrored to icr.io/galasadev for a limited number of releases to give you time to migrate, after which icr.io/galasadev will no longer receive updates.

What you need to do: If your automation or values.yaml references icr.io/galasadev, update it to icr.io/galasa. The galasaRegistry value in this chart already defaults to icr.io/galasa from v1.0.0 onwards — remove any override you may have set.

See Migrating to icr.io/galasa for full details.

Quick Start

Prerequisites

• Helm 3 or 4 installed
• Access to a Kubernetes cluster (v1.30.3 or later recommended)
• kubectl configured to access your cluster

Basic Installation

1. Add the Galasa Helm repository:

   helm repo add galasa https://galasa-dev.github.io/helm
   helm repo update

2. Download and configure values:

   curl -O https://raw.githubusercontent.com/galasa-dev/helm/main/charts/ecosystem/values.yaml

   Edit values.yaml and set:

   • galasaVersion: Your desired Galasa version (see releases)
   • externalHostname: The hostname for accessing your ecosystem (e.g., galasa.example.com)

3. Configure network access:

   Choose either Ingress (default) or Gateway API. For Ingress, update:

   ingress:
   enabled: trueingressClassName: nginx # Change to your IngressClass

   For Gateway API or HTTPS setup, see Network Access.

4. Configure authentication (Dex):

   Update the dex section in values.yaml:

   dex:
   config:
   issuer: https://galasa.example.com/dex # Use your hostnameconnectors:
   - type: github # Or another supported connectorid: githubname: GitHubconfig:
   clientID: $GITHUB_CLIENT_IDclientSecret: $GITHUB_CLIENT_SECRETredirectURI: https://galasa.example.com/dex/callback

   See Configuring Authentication for detailed setup.

5. Install the ecosystem:

   helm install my-galasa galasa/ecosystem -f values.yaml --wait

6. Verify the installation:

   helm test my-galasa

Your Galasa Ecosystem is now accessible at https://galasa.example.com/api/bootstrap

---

Table of Contents

• Galasa Helm Charts
  • Quick Start
    • Prerequisites
    • Basic Installation
  • Table of Contents
  • Configuration Guide
    • RBAC Setup
    • Network Access (Ingress/Gateway API)
      • Option 1: Ingress (Default)
      • Option 2: Gateway API (v0.47.0+)
    • Configuring Authentication (Dex)
      • GitHub Example
      • Other Identity Providers
    • Optional Configurations
      • Istio Service Mesh
      • Storage Class
      • Kafka Integration
      • Custom Logging (Log4j2)
      • Internal Certificates
  • Installation Guides
    • Remote Kubernetes Cluster
    • Minikube (Development)
      • Prerequisites
      • Linux Setup
      • macOS Setup
  • Operations
    • Verifying Installation
    • Upgrading
    • Uninstalling
    • Rotating Encryption Keys
      • Prerequisites
      • Automated Rotation (Linux/macOS)
      • Manual Rotation
  • Development
  • Support
  • Migrating to icr.io/galasa

---

Configuration Guide

RBAC Setup

If RBAC is enabled on your cluster, configure user permissions:

For chart versions after 0.23.0: RBAC is configured automatically during installation.

For chart version 0.23.0 and earlier: Apply RBAC manually:

kubectl apply -f https://raw.githubusercontent.com/galasa-dev/helm/ecosystem-0.23.0/charts/ecosystem/rbac.yaml

Admin access: Update rbac-admin.yaml to grant users the galasa-admin role for managing the Helm chart. Replace the placeholder username with actual usernames or add multiple subjects as needed.

Network Access (Ingress/Gateway API)

Choose one method to expose your Galasa services:

Option 1: Ingress (Default)

Most common for production deployments. Configure in values.yaml:

ingress:
enabled: trueingressClassName: nginx # Change to your IngressClass# For HTTPS, add:tls:
- hosts:
- galasa.example.comsecretName: galasa-tls-secret

See Kubernetes Ingress documentation for TLS setup.

Option 2: Gateway API (v0.47.0+)

Prerequisites:

• Gateway Controller installed
• Gateway API CRDs installed

For clusters with Gateway API support:

gateway:
enabled: truegatewayClassName: my-gateway-class# For HTTPS, add:tls:
certificateRefs:
- kind: Secretgroup: ""name: my-certificate-secret

Configuring Authentication (Dex)

Galasa uses Dex for authentication. Configure a connector to your identity provider:

GitHub Example

1. Create a GitHub OAuth App:

   • Go to GitHub OAuth Apps
   • Set Homepage URL to your external hostname (e.g., https://galasa.example.com)
   • Set Callback URL to https://galasa.example.com/dex/callback
   • Generate a client secret and save both the client ID and secret

2. Configure Dex in values.yaml:

   dex:
   config:
   issuer: https://galasa.example.com/dexconnectors:
   - type: githubid: githubname: GitHubconfig:
   clientID: $GITHUB_CLIENT_IDclientSecret: $GITHUB_CLIENT_SECRETredirectURI: https://galasa.example.com/dex/callback# Optional: Restrict to organization/teamorgs:
   - name: my-orgteams:
   - my-team

3. Store credentials securely (recommended):

   kubectl create secret generic github-oauth-credentials \
   --from-literal=GITHUB_CLIENT_ID="your-client-id" \
   --from-literal=GITHUB_CLIENT_SECRET="your-client-secret"

   Then reference the secret in values.yaml:

   dex:
   envFrom:
   - secretRef:
   name: github-oauth-credentials

Other Identity Providers

Dex supports many connectors including Microsoft, LDAP, OIDC, and more. See the Dex connectors documentation for configuration examples.

Optional Configurations

Istio Service Mesh

Galasa supports integration with Istio service mesh to automatically encrypt all pod-to-pod traffic using mutual TLS (mTLS).

Prerequisites:

• Istio 1.29+ installed in your Kubernetes cluster
• See Istio installation guide

Basic Configuration (Internal Traffic Only):

To enable mTLS for internal pod-to-pod traffic:

istio:
enabled: truemtlsMode: "STRICT"# Recommended for production

External Traffic Routing:

Istio can also handle external traffic routing. Choose one option:

Option 1: Istio with Kubernetes Gateway API (Recommended)

istio:
enabled: truemtlsMode: "STRICT"gatewayApi:
enabled: truegatewayClassName: "istio"# Use Istio's Gateway implementation

Option 2: Istio with Kubernetes Ingress

First, create an Istio IngressClass:

kubectl apply -f - <<EOFapiVersion: networking.k8s.io/v1kind: IngressClassmetadata:
name: istiospec:
controller: istio.io/ingress-controllerEOF

Then configure the chart's values:

istio:
enabled: truemtlsMode: "STRICT"ingress:
enabled: trueingressClassName: "istio"# Use Istio's Ingress controller

Note: When using Istio for external traffic, Istio handles both external ingress and internal mTLS encryption.

Configuration Options:

• istio.enabled: Enable or disable Istio integration (default: false)
• istio.mtlsMode: mTLS enforcement mode
  • STRICT: Only mTLS traffic allowed (recommended for production)
  • PERMISSIVE: Both mTLS and plaintext allowed (useful for migration)
  • DISABLE: mTLS disabled

How It Works:

When Istio is enabled:

1. All Galasa service pods receive an Istio sidecar proxy
2. The sidecar automatically encrypts all pod-to-pod traffic using mTLS
3. Application code continues to use HTTP URLs - encryption is transparent
4. Test pods launched by the Engine Controller also receive Istio sidecars

Migration Strategy:

For existing deployments, use a gradual migration approach:

1. Enable with PERMISSIVE mode:

   istio:
   enabled: truemtlsMode: "PERMISSIVE"

2. Upgrade your deployment:

   helm upgrade my-galasa galasa/ecosystem -f values.yaml --wait

3. Verify all services are working:

   # Check that all pods have Istio sidecars (should show 2 containers per pod)
   kubectl get pods
   # Verify mTLS is enabled by checking Istio proxy config
   istioctl proxy-status 

4. Switch to STRICT mode:

   istio:
   enabled: truemtlsMode: "STRICT"

5. Upgrade again:

   helm upgrade my-galasa galasa/ecosystem -f values.yaml --wait

Troubleshooting:

• Pods not getting sidecars: Verify Istio is installed with kubectl get pods -n istio-system
• Connection failures: Use PERMISSIVE mode during migration, then switch to STRICT
• Check Istio proxy logs:kubectl logs <pod-name> -c istio-proxy

Storage Class

If your cluster requires a specific StorageClass:

storageClass: my-storage-class

Kafka Integration

To publish Galasa events to Kafka:

1. Create a secret with your Kafka token:

   apiVersion: v1kind: Secretmetadata:
   name: event-streams-tokendata:
   GALASA_EVENT_STREAMS_TOKEN: <base64-encoded-token>

2. Apply the secret before installing the chart

See Kafka extension documentation for details.

Custom Logging (Log4j2)

Customize log format by setting log4j2Properties in values.yaml:

log4j2Properties: | status = error name = Default appender.console.type = Console appender.console.name = stdout appender.console.layout.type = PatternLayout appender.console.layout.pattern = %d{dd/MM/yyyy HH:mm:ss.SSS} %-5p %c{1.} - %m%n rootLogger.level = debug rootLogger.appenderRef.stdout.ref = stdout

For JSON templates, create a ConfigMap and reference it:

log4jJsonTemplatesConfigMapName: my-json-layouts

Internal Certificates

For connecting to servers with internal or corporate certificates:

1. Create a ConfigMap with your certificates:

   kubectl create configmap my-certificates \
   --from-file=/path/to/certificate1.pem \
   --from-file=/path/to/certificate2.pem

2. Reference it in values.yaml:

   certificatesConfigMapName: my-certificates

---

Installation Guides

Remote Kubernetes Cluster

Follow the Quick Start guide above, ensuring you've configured:

• Network access (Ingress or Gateway API)
• Authentication (Dex)
• Any optional features you need

Minikube (Development)

⚠️Minikube is for development/testing only, not production use.

Prerequisites

• Minikube installed and running
• Verify with: minikube status

Linux Setup

1. Enable Ingress:

   minikube addons enable ingress

2. Configure /etc/hosts:

   # Add this line (replace IP with output of 'minikube ip')
   192.168.49.2 galasa.local

3. Configure values.yaml:

   • Set externalHostname: galasa.local
   • Configure Dex and Ingress as described above

4. Install:

   helm install my-galasa ./charts/ecosystem -f values.yaml --wait

5. Verify:

   kubectl get pods # Wait for all pods to be Ready
   helm test my-galasa

macOS Setup

1. Enable Ingress:

   minikube addons enable ingress

2. Configure /etc/hosts:

   # Add this line
   127.0.0.1 galasa.local

3. Configure CoreDNS for internal resolution:

   a. Get Minikube IP:

   minikube ip # Note this IP (e.g., 192.168.49.2)

   b. Edit CoreDNS ConfigMap:

   kubectl -n kube-system edit configmap coredns

   c. Add this entry (replace IP with your Minikube IP):

   galasa.local:53 {hosts {192.168.49.2 galasa.localfallthrough}}

   d. Restart CoreDNS:

   kubectl -n kube-system rollout restart deployment coredns

4. Configure values.yaml:

   • Set externalHostname: galasa.local
   • Configure Dex and Ingress as described above

5. Install:

   helm install my-galasa ./charts/ecosystem -f values.yaml --wait

6. Start tunnel (keep running):

   minikube tunnel

7. Verify (in another terminal):

   kubectl get pods # Wait for all pods to be Ready
   helm test my-galasa

---

Operations

Verifying Installation

After installation, verify your ecosystem is working:

helm test<release-name>

Expected output:

TEST SUITE: my-galasa-validate
Last Started: Mon Mar 3 11:44:24 2025
Last Completed: Mon Mar 3 11:45:45 2025
Phase: Succeeded

Access your ecosystem:

• Bootstrap URL: https://<your-hostname>/api/bootstrap
• Web UI: https://<your-hostname>

Monitor pods:

kubectl get pods

All pods should show Running status and 1/1 ready.

Upgrading

To upgrade to a newer Galasa version:

helm repo update
helm upgrade <release-name> galasa/ecosystem \
--reuse-values \
--set galasaVersion=1.0.0 \
--wait

Or update your values.yaml and run:

helm upgrade <release-name> galasa/ecosystem -f values.yaml --wait

Upgrading to v1.0.0 or later? See Migrating to icr.io/galasa below.

Uninstalling

helm uninstall <release-name>

This removes all Kubernetes resources created by the chart.

Rotating Encryption Keys

Galasa encrypts credentials using AES-256-GCM. To rotate encryption keys:

Prerequisites

• kubectl (v1.30.3+)
• galasactl (0.38.0+)
• openssl (3.3.2+)
• Permissions to manage Secrets in your namespace
• Valid personal access token for Galasa

⚠️ Backup your credentials first:

galasactl secrets get --format yaml > backup.yaml

Automated Rotation (Linux/macOS)

Use the provided script:

./rotate-encryption-keys.sh \
--release-name my-galasa \
--namespace default \
--bootstrap https://galasa.example.com/api/bootstrap

The script will:

1. Generate a new encryption key
2. Update the Kubernetes Secret
3. Restart API and engine controller pods
4. Re-encrypt all existing credentials
5. Clean up fallback keys

Manual Rotation

Click to expand manual steps

1. Backup existing secrets:

   galasactl secrets get --format yaml > backup.yaml

2. Find the encryption secret:

   kubectl get secrets
   # Look for: <release-name>-encryption-secret

3. Get current encryption keys:

   kubectl get secret <encryption-secret-name> \
   --output jsonpath='{ .data.encryption-keys\.yaml }'| \
   openssl base64 -d -A > current-keys.yaml

4. Generate new key:

   openssl rand -base64 32

5. Update keys file: Edit current-keys.yaml to move the old key to fallback and add the new key:

   encryptionKey: <new-key-from-step-4>fallbackDecryptionKeys:
   - <old-key-from-step-3>

6. Encode and update secret:

   NEW_KEYS=$(openssl base64 -in current-keys.yaml | tr -d '\n')
   kubectl patch secret <encryption-secret-name> \
   --type='json' \
   -p="[{'op': 'replace', 'path': '/data/encryption-keys.yaml', 'value': '$NEW_KEYS'}]"

7. Restart services:

   kubectl rollout restart deployment <release-name>-api
   kubectl rollout status deployment <release-name>-api
   kubectl rollout restart deployment <release-name>-engine-controller
   kubectl rollout status deployment <release-name>-engine-controller

8. Re-encrypt credentials:

   galasactl resources apply -f backup.yaml

9. Verify:

   galasactl secrets get --format yaml
   # Compare with backup.yaml to ensure secrets are readable

---

Development

To install the latest development version:

1. Clone this repository:

   git clone https://github.com/galasa-dev/helm.git
   cd helm

2. Configure values.yaml for development:

   galasaVersion: maingalasaRegistry: ghcr.io/galasa-devgalasaBootImage: galasa-boot-embeddedpullPolicy: AlwaysgalasaWebUiImage: webuiarchitecture: amd64 # or arm64externalHostname: galasa.local # For Minikube

3. Configure Ingress and Dex as described in the Configuration Guide

4. Install from local chart:

   helm install my-galasa ./charts/ecosystem -f values.yaml --wait

---

Migrating to icr.io/galasa

From Galasa v1.0.0, all Docker images are published to the public IBM Container Registry namespace icr.io/galasa. No credentials are required to pull from this registry.

What is changing

Before v1.0.0	From v1.0.0
icr.io/galasadev	icr.io/galasa

Images will continue to be published to icr.io/galasadev for a limited number of releases after v1.0.0 to give you time to switch. After that grace period, icr.io/galasadev will no longer receive updates and you must use icr.io/galasa.

Is any action required for the Helm chart?

The galasaRegistry value in the chart already defaults to icr.io/galasa from v1.0.0. If you:

• Use the default — no action needed.
• Pinned galasaRegistry: icr.io/galasadev in your values.yaml — remove or update that line:

  galasaRegistry: "icr.io/galasa"

What if I pull images outside of the Helm chart?

If you have scripts, CI pipelines, or other automation that pulls Galasa images directly, update the registry prefix in those references:

# Before
icr.io/galasadev/galasa-boot-embedded-amd64:0.x.x
# After
icr.io/galasa/galasa-boot-embedded-amd64:1.0.0

Image names and tags remain the same — only the registry namespace changes.

---

Support

• Documentation:galasa.dev
• Issues:GitHub Issues
• Releases:Galasa Releases