Getting Started

By the end of this page, you will have installed the OpenMCF CLI, deployed a PostgreSQL database to a local Kubernetes cluster, verified it is running, and torn it down. The entire process takes about 10 minutes.

You will use KubernetesPostgres — one of OpenMCF's 360+ deployment components — as your first resource. It runs on a local Kind cluster, so you do not need cloud provider credentials or a paid account to get started.

What You'll Need

Install these tools before proceeding:

This guide uses Pulumi as the IaC engine. If you prefer OpenTofu or Terraform, see Dual IaC Engines for setup instructions.

Install OpenMCF

brew install plantonhq/tap/openmcf

Verify the installation:

openmcf version

Create a Local Cluster

Create a Kubernetes cluster using Kind:

kind create cluster --name openmcf-quickstart

Confirm the cluster is running:

kubectl cluster-info --context kind-openmcf-quickstart

Write Your Manifest

Create a file named postgres.yaml:

apiVersion: kubernetes.openmcf.org/v1
kind: KubernetesPostgres
metadata:
  name: my-first-postgres
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: organization
    pulumi.openmcf.org/project: getting-started
    pulumi.openmcf.org/stack.name: dev
spec:
  namespace:
    value: my-first-postgres
  createNamespace: true
  container:
    replicas: 1
    resources:
      requests:
        cpu: 50m
        memory: 100Mi
      limits:
        cpu: 500m
        memory: 512Mi
    diskSize: 1Gi

Every OpenMCF manifest follows the Kubernetes Resource Model (KRM) — the same apiVersion, kind, metadata, spec structure used by Kubernetes itself. Here is what each section does:

• apiVersion and kind identify this as a KubernetesPostgres resource. OpenMCF has 360+ component kinds across 17 cloud providers, each with its own apiVersion and kind.
• metadata.name names this resource. The name is used in state tracking, logging, and resource identification.
• metadata.labels control how OpenMCF processes the manifest:
  • openmcf.org/provisioner: pulumi tells the CLI to route this deployment through the Pulumi engine. The alternative is tofu for OpenTofu/Terraform.
  • The three pulumi.openmcf.org/* labels configure the Pulumi stack identity — where deployment state is stored. For local development, any values work.
• spec defines the desired state of the resource. Each component kind has its own spec fields, defined by Protocol Buffer schemas with built-in validation.

For a deeper explanation of the manifest model, see Manifests.

Validate the Manifest

openmcf validate -f postgres.yaml

Validation checks the manifest against the KubernetesPostgres Protocol Buffer schema. It catches structural errors — missing required fields, invalid field types, values outside allowed ranges — before you attempt a deployment.

If validation passes, the CLI prints a confirmation. If it fails, the error message identifies the exact field and constraint that was violated.

Prepare for Deployment

Two setup steps before deploying:

Configure a local Pulumi backend. Pulumi needs a backend to store deployment state. For local development, use file-based storage:

pulumi login --local

This stores state in ~/.pulumi/ on your machine. For team or production use, OpenMCF supports Pulumi Cloud, S3, GCS, and Azure Blob backends. See State Management for details.

Initialize the stack. A Pulumi stack is a unit of deployment state — it tracks what resources exist and their current configuration. Create one for this deployment:

openmcf init -f postgres.yaml

This reads the stack labels from the manifest (local/getting-started/dev) and registers the stack with your configured backend. The command is idempotent — running it again on an existing stack is safe.

Deploy

openmcf apply -f postgres.yaml

The CLI loads the manifest, resolves the Pulumi module for KubernetesPostgres from the OpenMCF repository, and executes the deployment. You will see Pulumi's output as it creates Kubernetes resources — a StatefulSet, Service, PersistentVolumeClaim, and supporting objects.

The first run takes longer because the CLI clones the IaC module from GitHub. Subsequent runs use the cached module at ~/.openmcf/modules/.

Verify

Check that the PostgreSQL pod is running:

kubectl get pods -n my-first-postgres

You should see a pod named my-first-postgres-postgresql-0 with status Running. It may take a minute for the pod to pull the PostgreSQL image and start.

Check the service:

kubectl get svc -n my-first-postgres

Clean Up

Destroy the deployed resources:

openmcf destroy -f postgres.yaml

This removes all Kubernetes resources that were created by the deployment.

Optionally, delete the Kind cluster:

kind delete cluster --name openmcf-quickstart

What Just Happened

When you ran openmcf apply, the CLI executed this pipeline:

1. Loaded the manifest from postgres.yaml and applied Protocol Buffer validation
2. Read the openmcf.org/provisioner: pulumi label and routed execution to the Pulumi engine
3. Resolved the Pulumi module for KubernetesPostgres — a Go program that translates the spec into Kubernetes resources
4. Built a stack input from the manifest and passed it to the Pulumi program as configuration
5. Executed pulumi up, which created a StatefulSet, Service, PersistentVolumeClaim, and associated resources in your cluster

This is the same workflow for every deployment component in OpenMCF. Whether you deploy an AWS S3 bucket, a GCP Cloud SQL instance, or a Cloudflare Worker, the pattern is identical: write a manifest, validate, init, apply. The manifest fields change; the workflow does not.

Next Steps

You have deployed your first resource with OpenMCF. Here is where to go next:

• Understand the model. Read Core Concepts to learn how deployment components, manifests, validation, and the dual IaC engine system work together.
• Deploy to a cloud provider. Follow the AWS S3 Bucket tutorial or the Multi-Provider tutorial to deploy real cloud infrastructure.
• Go deeper with Kubernetes. The Kubernetes Postgres tutorial builds on this guide with custom databases, named users, resource tuning, and runtime overrides.
• Set up cloud credentials. Configure AWS, GCP, or Azure for production deployments.
• Explore the catalog. Browse all 360+ deployment components across 17 cloud providers.
• Troubleshoot issues. Check the Troubleshooting Guide if you run into problems.