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: PostgresKubernetes
metadata:
  name: dev-database
spec:
  container:
    replicas: 1
    resources:
      limits:
        cpu: 500m
        memory: 1Gi

Step 3: Validate (Optional)

Validate your manifest before deployment:

project-planton validate --manifest 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:

project-planton pulumi up --manifest 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 --manifest config.yaml

# Deploy with Pulumi
project-planton pulumi up --manifest config.yaml --stack org/project/env

# Deploy with Terraform
project-planton tofu apply --manifest config.yaml

# Override specific values
project-planton pulumi up \
  --manifest config.yaml \
  --set spec.container.cpu=500m \
  --stack org/project/env

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