Skip to main content

Getting Started with Petra

Petra is a hardened Kubernetes distribution built for compliant, air-gap-capable environments. This guide covers building and using the CLI.

Prerequisites​

  • Go 1.24+
  • AWS credentials configured (profile or environment variables)
  • AWS CLI v2

Build the CLI​

cd cli
go build -o petra .
./petra version

Define a Cluster​

Create a cluster spec file:

apiVersion: petra.sh/v1alpha1
kind: Cluster
metadata:
  name: petra-dev
spec:
  kubernetes:
    version: v1.35.3+k3s1
  profile: standard
  target:
    type: aws
    region: us-west-1
  nodes:
    controlPlane:
      count: 1
      instanceType: m5a.large
    workers:
      count: 2
      instanceType: m5a.large
  addons:
    cilium:
      enabled: true
      hubble: true
    flux:
      enabled: true
    certManager:
      enabled: true

Provision a Cluster​

# Boot the cluster (~2 minutes)
petra up -f cluster.yaml

# Check status
petra status -f cluster.yaml

# Retrieve kubeconfig
petra kubeconfig -f cluster.yaml

# Access via SSM (no SSH)
aws ssm start-session --target <instance-id> --region us-west-1

What Happens During Bootstrap​

Petra provisions infrastructure via the AWS SDK and bootstraps the cluster through five phases:

PhaseComponentTime
0SSM Agent~15s
1k3s v1.35.3 (FIPS)~12s
2Helm CLIunder 1s
3Cilium 1.19.2~38s
4Flux v2~37s
5Platform Kustomization~5s

Total bootstrap time on m5a.large: under 2 minutes.

Tear Down​

petra destroy -f cluster.yaml

All resources are tagged and discovered by tag during teardown. No state file required.

Next Steps​