Portefaix docs GitHub

Your First Portefaix Cluster

This tutorial walks you through bootstrapping a fully operational Portefaix platform on a cloud provider of your choice. By the end, you will have a running Kubernetes cluster with GitOps, observability, and policy enforcement configured — and you will understand how each piece fits together.

What you will learn: how to provision cloud infrastructure with Terraform, connect ArgoCD to a Git repository, deploy platform stacks, and verify the installation. This tutorial is designed for first-time Portefaix users.

Before you begin

You need the following tools installed and configured on your workstation:

  • Terraform ≥ 1.5 — infrastructure provisioning
  • kubectl — Kubernetes CLI
  • Helm ≥ 3.12 — chart management
  • ArgoCD CLI (argocd) — GitOps operations
  • Git — version control
  • Cloud provider CLI (gcloud, aws, or az)

You also need:

  • A cloud provider account with permissions to create Kubernetes clusters and IAM resources
  • A GitHub (or GitLab) account for your GitOps repository

Step 1 — Fork the Portefaix repositories

Portefaix uses two main repositories. Fork both to your GitHub account — ArgoCD will pull manifests from your forks, allowing you to customise settings without modifying upstream. 

# Fork these repositories on GitHub, then clone them locally
git clone https://github.com/YOUR_ORG/portefaix-kubernetes
git clone https://github.com/YOUR_ORG/portefaix-infrastructure

Set your organisation name as an environment variable for the commands below:

export PORTEFAIX_ORG="your-github-org"
export PORTEFAIX_ENV="staging"           # or "production"
export CLOUD="gcp"                       # gcp | aws | azure | scaleway

Step 2 — Provision cloud infrastructure

Navigate to the Terraform module for your chosen cloud provider. Each module creates a managed Kubernetes cluster, networking, IAM roles for workload identity, and storage buckets for Terraform state. 

cd portefaix-infrastructure/terraform/$CLOUD/cluster
cp terraform.tfvars.example terraform.tfvars
# Edit terraform.tfvars with your project ID, region, and cluster settings
terraform init
terraform plan -out=tfplan
terraform apply tfplan

After apply completes, Terraform outputs your cluster credentials. Fetch them: 

# GCP
gcloud container clusters get-credentials portefaix-$PORTEFAIX_ENV --region europe-west1

# AWS
aws eks update-kubeconfig --name portefaix-$PORTEFAIX_ENV --region eu-west-1

# Azure
az aks get-credentials --resource-group portefaix --name portefaix-$PORTEFAIX_ENV

Verify the cluster is reachable:

kubectl get nodes

Step 3 — Install ArgoCD

ArgoCD is the GitOps engine that continuously reconciles your cluster state with the manifests in Git. Install it into a dedicated namespace: 

kubectl create namespace argocd

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

helm install argocd argo/argo-cd \
  --namespace argocd \
  --version 7.x.x \
  --values portefaix-kubernetes/gitops/argocd/values-$CLOUD.yaml \
  --wait

Retrieve the initial admin password and log in: 

argocd admin initial-password -n argocd

argocd login localhost:8080 \
  --username admin \
  --password "$(argocd admin initial-password -n argocd | head -1)" \
  --insecure

Step 4 — Bootstrap the App of Apps

Portefaix uses the app-of-apps pattern: a single root ArgoCD Application manages all other Applications. Apply the bootstrap manifest to register it: 

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

ArgoCD will now pull manifests from your forked repository and begin reconciling. Watch the sync progress: 

argocd app list
argocd app sync portefaix-bootstrap
argocd app wait portefaix-bootstrap --health

Step 5 — Verify the installation

Once all Applications are Healthy and Synced, verify the core platform components are running: 

# Observability stack
kubectl get pods -n monitoring

# Policy engine
kubectl get pods -n kyverno

# Certificate management
kubectl get pods -n cert-manager

# Ingress
kubectl get pods -n ingress-nginx

Open the ArgoCD UI to see all managed applications: 

kubectl port-forward svc/argocd-server -n argocd 8080:443
# Visit https://localhost:8080

What you built

You now have a Portefaix platform with:

  • A managed Kubernetes cluster provisioned with Terraform
  • ArgoCD continuously reconciling cluster state from Git
  • Kyverno enforcing platform policies
  • Prometheus + Grafana for metrics and dashboards
  • Cert-manager issuing TLS certificates automatically
  • External Secrets Operator syncing secrets from your cloud vault

Next steps

Now that you have a running cluster, explore the rest of the documentation: