Getting Started

This guide will help you install the ProjectPlanton CLI and deploy your first infrastructure resource.

Prerequisites

Before you begin, ensure you have the following installed:

• Git - Required for cloning modules
• Pulumi CLI - For Pulumi deployments (brew install pulumi)
• Terraform/OpenTofu CLI - For Terraform deployments (brew install opentofu)
• Cloud provider credentials - AWS, GCP, Azure, etc. configured locally

Installation

Install the ProjectPlanton CLI using Homebrew:

brew install project-planton/tap/project-planton

Verify the installation:

project-planton version

Your First Deployment

Let's deploy a PostgreSQL database to a local Kubernetes cluster.

Step 1: Create a Local Kubernetes Cluster

If you don't have a Kubernetes cluster, create one using Kind:

brew install kind
kind create cluster

Step 2: Create Your Manifest

Create a file named postgres.yaml:

apiVersion: kubernetes.project-planton.org/v1
kind: KubernetesPostgres
metadata:
  name: dev-database
  labels:
    project-planton.org/provisioner: pulumi
spec:
  container:
    replicas: 1
    resources:
      limits:
        cpu: 500m
        memory: 1Gi

Step 3: Validate (Optional)

Validate your manifest before deployment:

project-planton validate -f postgres.yaml

This runs validation rules defined in the protobuf, catching errors like:

• Invalid CPU format
• Replica count out of range
• Missing required fields

Step 4: Deploy

Set up a local Pulumi backend:

pulumi login --local

Deploy the resource using the unified kubectl-style command:

# Simple unified command (automatically detects provisioner from label)
project-planton apply -f postgres.yaml

# Or use the traditional Pulumi-specific command
project-planton pulumi up -f postgres.yaml --stack org/dev/local

Step 5: Verify

Check that the PostgreSQL instance is running:

kubectl get pods
# You should see: dev-database-postgresql-0

What Happened?

Behind the scenes, the CLI:

1. Read and validated your manifest
2. Identified the PostgresKubernetes deployment component
3. Cloned the corresponding Pulumi module from GitHub
4. Set up the environment with your manifest as input
5. Delegated to Pulumi to deploy the resources
6. PostgreSQL is now running in your cluster!

Next Steps

• Explore Components: Check out other deployment components
• Learn Concepts: Understand the architecture
• Deploy to Cloud: Try deploying to AWS, GCP, or Azure

Common Commands

# Validate a manifest
project-planton validate -f config.yaml

# Unified kubectl-style commands (provisioner auto-detected from manifest)
project-planton apply -f config.yaml
project-planton destroy -f config.yaml
# Or use 'delete' as an alias
project-planton delete -f config.yaml

# Provisioner-specific commands (still supported)
project-planton pulumi up -f config.yaml --stack org/project/env
project-planton tofu apply -f config.yaml

# Override specific values
project-planton apply -f config.yaml --set spec.container.cpu=500m

Troubleshooting

"Module not found"

The CLI clones modules from GitHub. Ensure you have:

• Git installed and configured
• Network connectivity to GitHub

"Validation failed"

Check the error message for specific field validation failures. Common issues:

• Invalid resource units (e.g., CPU should be "500m" not "500")
• Missing required fields
• Values outside allowed ranges

"Pulumi/Terraform not found"

Install the required IaC tool:

brew install pulumi    # For Pulumi deployments
brew install opentofu  # For Terraform deployments

Get Help

• GitHub Issues: Report bugs or request features
• Documentation: Browse the full documentation
• Examples: Check the repository for example manifests