Deploy Portefaix on IBM Cloud

This guide shows you how to deploy a Portefaix platform on IBM Cloud using IBM Kubernetes Service (IKS), Cloud Object Storage (COS) for Terraform state, and the IBM Cloud CLI for cluster management.

Prerequisites

• IBM Cloud account with an API key (Administrator role on the target resource group)
• ibmcloud CLI with the Kubernetes Service and Container Registry plugins
• Terraform ≥ 1.5, kubectl, and Helm installed locally

1. Configure your environment

export IC_API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export IAAS_CLASSIC_USERNAME="your-classic-username"
export IAAS_CLASSIC_API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

export IBM_REGION="eu-de"     # eu-de | eu-gb | us-south | us-east | ap-north
export IBM_RG="portefaix"     # resource group name
export PORTEFAIX_ENV="staging"

. ./portefaix.sh ibmcloud

# Authenticate the CLI
ibmcloud login --apikey "$IC_API_KEY" -r "$IBM_REGION" -g "$IBM_RG"
ibmcloud ks init

2. Create Terraform remote state storage

IBM Cloud Object Storage (COS) is S3-compatible when accessed with HMAC credentials. Create a COS instance and generate HMAC keys for Terraform:

# Create a COS service instance
ibmcloud resource service-instance-create portefaix-cos \
  cloud-object-storage standard global \
  -g "$IBM_RG"

# Create HMAC credentials (required for S3-compatible API access)
ibmcloud resource service-key-create portefaix-cos-hmac Writer \
  --instance-name portefaix-cos \
  --parameters '{"HMAC":true}'

# Extract the HMAC access key and secret
ibmcloud resource service-key portefaix-cos-hmac --output JSON | \
  jq '.credentials.cos_hmac_keys'

export AWS_ACCESS_KEY_ID="<access_key_id from HMAC output>"
export AWS_SECRET_ACCESS_KEY="<secret_access_key from HMAC output>"

# Create a bucket for Terraform state
ibmcloud cos bucket-create \
  --bucket portefaix-tfstate \
  --ibm-service-instance-id "$(ibmcloud resource service-instance portefaix-cos --output JSON | jq -r '.[0].id')" \
  --region "$IBM_REGION"

3. Provision the VPC with Terraform

cd portefaix-infrastructure/terraform/ibmcloud/vpc
cp terraform.tfvars.example terraform.tfvars

region           = "eu-de"
resource_group   = "portefaix"
vpc_name         = "portefaix-staging"

terraform init \
  -backend-config="bucket=portefaix-tfstate" \
  -backend-config="key=vpc/$PORTEFAIX_ENV.tfstate" \
  -backend-config="region=$IBM_REGION" \
  -backend-config="endpoint=https://s3.$IBM_REGION.cloud-object-storage.appdomain.cloud"

terraform plan -out=tfplan
terraform apply tfplan

4. Provision the IKS cluster with Terraform

cd portefaix-infrastructure/terraform/ibmcloud/iks
cp terraform.tfvars.example terraform.tfvars

region           = "eu-de"
resource_group   = "portefaix"
cluster_name     = "portefaix-staging"
k8s_version      = "1.31"
worker_flavor    = "bx2.4x16"
worker_count     = 3

terraform plan -out=tfplan
terraform apply tfplan

5. Fetch cluster credentials

ibmcloud ks cluster config \
  --cluster portefaix-staging \
  --admin

kubectl get nodes
NAME            STATUS   ROLES    AGE   VERSION
10.242.0.10     Ready    <none>   13m   v1.31.1+IKS
10.242.0.7      Ready    <none>   29m   v1.31.1+IKS
10.242.128.10   Ready    <none>   12m   v1.31.1+IKS
10.242.128.7    Ready    <none>   29m   v1.31.1+IKS
10.242.64.6     Ready    <none>   29m   v1.31.1+IKS
10.242.64.8     Ready    <none>   13m   v1.31.1+IKS

6. Deploy Portefaix stacks via ArgoCD

helm repo add argo https://argoproj.github.io/argo-helm
helm repo update

helm install argocd argo/argo-cd \
  --namespace argocd --create-namespace \
  --values portefaix-kubernetes/gitops/argocd/values-ibmcloud.yaml \
  --wait

kubectl apply -f portefaix-kubernetes/gitops/argocd/bootstrap/app-of-apps-ibmcloud-$PORTEFAIX_ENV.yaml

argocd app wait portefaix-bootstrap --health --timeout 600

Stacks available on IBM Cloud