Complete Installation Guide

Step-by-step guide for deploying IBM GCM 2.0.1 using the OVF template

Prerequisites

Before you begin, ensure you have the following:

VMware Environment

  • vSphere/ESXi 6.7 or later
  • vCenter (recommended)
  • Sufficient resources available

Network Requirements

  • Static IP address
  • DNS server configured
  • Gateway accessible
  • Internet connectivity

Resources

  • GCM 2.0.1 OVF template
  • GCM installation package
  • IBM Entitled Registry key

Step 1: Deploy OVF Template

1

Deploy in vSphere Client

  1. Right-click on your datacenter/cluster
  2. Select "Deploy OVF Template"
  3. Browse to GCM 2.0.1 OVF file
  4. Follow wizard to complete deployment
2

Configure VM Resources

Size vCPUs RAM Disk Use Case
xsmall 24 48 GB 150 GB PoC/Testing
small 32 64 GB 300 GB Small Production
medium 48 96 GB 500 GB Medium Production
large 64 128 GB 1 TB Large Production
3

Power On and Login

After deployment completes:

  • Power on the VM
  • Open console (VMRC recommended)
  • Login with provided credentials
Username: root
Password: (provided with OVF)
Important: Use VMRC console for initial configuration. SSH may not work until network is configured.

Step 2: Configure VM Network & Hostname

Run the VM configuration wizard to set up networking, hostname, and firewall.

cd /root
./01-configure_vm.sh

Configuration Wizard

1

Network Configuration

You'll be prompted for:

  • IP Address: Static IP or DHCP
  • Subnet Mask: e.g., 255.255.255.0
  • Gateway: Default gateway IP
  • DNS Servers: Primary and secondary
2

Hostname Configuration

  • Short hostname: e.g., gcm-prod
  • Domain name: e.g., company.com
  • FQDN: Will be gcm-prod.company.com
3

Time Configuration

  • Timezone: Select your timezone
  • NTP Server: Optional, for time synchronization
4

Firewall Configuration

Auto-configure firewall? (Recommended: Yes)

  • Opens port 30443 (OIDC/Keycloak)
  • Opens port 31443 (GCM Application)

What the Script Does

  • ✅ Applies network configuration with automatic CIDR conversion
  • ✅ Sets hostname and FQDN
  • ✅ Configures timezone and NTP
  • ✅ Configures firewall rules (ports 30443, 31443)
  • ✅ Tests connectivity (gateway, DNS, internet, FQDN)
  • ✅ Saves configuration to /etc/gcm/vm-config.env
  • ✅ Creates backup of previous configuration

Key Features (v1.0.0)

Smart CIDR Conversion

Automatically converts subnet masks (255.255.255.0) to CIDR notation (/24) for NetworkManager compatibility

Improved Connection Detection

Multiple fallback methods to find the correct NetworkManager connection, even with non-standard naming

Comprehensive Testing

Validates gateway, DNS, internet connectivity, and FQDN resolution after configuration

Configuration Backup

Automatically backs up existing configuration before making changes

Expected Time: 2-3 minutes
Note: If you encounter network configuration errors, see the Network Configuration Troubleshooting section.

Step 3: Configure GCM Application

Run the GCM configuration wizard to set up application parameters.

cd /root
./02-configure_gcm.sh

Configuration Options

GCM Package Location

Script will auto-detect the GCM package. Confirm or specify custom location.

Sizing Model

Choose based on your VM resources:

  • xsmall: 24 vCPU / 48GB
  • small: 32 vCPU / 64GB
  • medium: 48 vCPU / 96GB
  • large: 64 vCPU / 128GB

Storage Configuration

  • local-path: Recommended for single-node
  • rook-ceph: For multi-node clusters
  • custom: Specify your own

Platform Versions

  • K3s: 1.30.5 (IBM validated)
  • Helm: 3.13.x (IBM required)

What the Script Does

  • ✅ Validates GCM package
  • ✅ Checks system resources
  • ✅ Saves configuration to /etc/gcm/gcm-config.env
Expected Time: 1-2 minutes

Step 4: Install GCM

Run the installation script to deploy GCM 2.0.1.

cd /root
./04-install_gcm_ovf.sh

Installation Process

1

Pre-Flight Checks (~30 seconds)

Validates all configurations, checks system requirements, verifies network connectivity

2

K3s Installation (~2 minutes)

Installs Kubernetes v1.30.5 and configures local-path storage

3

Helm Installation (~1 minute)

Installs Helm 3.13.x package manager

4

Firewall Configuration (~5 seconds)

Opens required ports for GCM access

5

GCM Installation (~15-20 minutes)

Deploys all GCM services, configures OIDC/Keycloak, waits for pods to be ready

During Installation

When prompted about "Pending PVC" (if using local-path storage):

  • This is NORMAL behavior
  • Type yes to continue
  • PVCs will bind when pods start
Total Installation Time: 20-25 minutes

Step 5: Access GCM

After installation completes, you'll see the success message with access details.

Installation Complete Message

╔════════════════════════════════════════════════════════════════╗
║ Installation Complete!
╚════════════════════════════════════════════════════════════════╝

[✓] GCM 2.0.1 installed successfully!

[INFO] ═══════════════════════════════════════════════════════════════
[INFO]   GCM APPLICATION ACCESS
[INFO] ═══════════════════════════════════════════════════════════════

[INFO]   URL:      https://your-fqdn.com:31443
[INFO]   Username: gcmadmin
[INFO]   Password: 

[INFO] ═══════════════════════════════════════════════════════════════
[INFO]   OIDC/KEYCLOAK ADMIN ACCESS
[INFO] ═══════════════════════════════════════════════════════════════

[INFO]   URL:      https://your-fqdn.com:30443
[INFO]   Username: gcmadmin
[INFO]   Password: 

[INFO] ═══════════════════════════════════════════════════════════════
[INFO]   SYSTEM STATUS
[INFO] ═══════════════════════════════════════════════════════════════

[INFO]   Active Pods:      31/31 Running (100%)
[INFO]   Completed Jobs:   4 (one-time setup tasks)
[INFO]   Storage:          local-path
[INFO]   Sizing:           xsmall

Access URLs

GCM Application

https://your-fqdn:31443

Main GCM web interface for key management

OIDC Admin Console

https://your-fqdn:30443

Keycloak admin console for user management

Troubleshooting

Network Issues

Cannot reach gateway or DNS

Solution:

# Re-run VM configuration
./01-configure_vm.sh

FQDN not resolving

Solutions:

  • Add DNS A record: your-fqdn -> your-ip
  • Or add to /etc/hosts on client machines

Installation Issues

Pre-flight checks fail

Solution:

  • Review error messages carefully
  • Fix issues and re-run ./04-install_gcm_ovf.sh

Pods not starting

Diagnostic commands:

# Check pod status
kubectl get pods -n gcmapp

# Check specific pod logs
kubectl logs  -n gcmapp

# Check events
kubectl get events -n gcmapp --sort-by='.lastTimestamp'

Post-Installation

Verify Installation

# Check all pods
kubectl get pods -n gcmapp

# Check services
kubectl get svc -n gcmapp

# Check storage
kubectl get pvc -n gcmapp

Access Logs

# Installation logs
ls -l /root/gcmapp/deployment_logs/

# View specific log
cat /root/gcmapp/deployment_logs/

Retrieve Credentials Later

# OIDC Username
kubectl get secret -n gcmapp oidc-admin-secret -o jsonpath='{.data.KC_BOOTSTRAP_ADMIN_USERNAME}' | base64 -d

# OIDC Password
kubectl get secret -n gcmapp oidc-admin-secret -o jsonpath='{.data.KC_BOOTSTRAP_ADMIN_PASSWORD}' | base64 -d

Configuration Files

All configurations are saved in /etc/gcm/:

  • vm-config.env - VM network and hostname settings
  • gcm-config.env - GCM application settings
  • backups/ - Backup copies of previous configurations

Quick Reference

Installation Summary

Step Script Time What It Does
1 Deploy OVF 5-10 min Deploy VM template in vSphere
2 ./01-configure_vm.sh 2-3 min Configure network, hostname, firewall
3 ./02-configure_gcm.sh 1-2 min Configure GCM sizing and storage
4 ./04-install_gcm_ovf.sh 20-25 min Install K3s, Helm, and GCM
Total 30-40 min Complete GCM deployment

Essential Commands

View Pods

kubectl get pods -n gcmapp

View Pod Details

kubectl describe pod  -n gcmapp

View Logs

kubectl logs  -n gcmapp

Restart Pod

kubectl delete pod  -n gcmapp

Check Storage

kubectl get pvc -n gcmapp

Check Services

kubectl get svc -n gcmapp