Provisioning a DigitalOcean Cluster

Prerequisites

Before running any kb infra do commands, you need two things:

• doctl installed and authenticated
• A DigitalOcean API token set in your environment

Authenticate doctl

Run the setup command. It checks whether doctl already has credentials and prompts for doctl auth init if not:

kb infra do setup

A successful run prints: Authenticated as you@example.com (active).

Set the API token

The OpenTofu DigitalOcean provider reads the token from DIGITALOCEAN_TOKEN or DIGITALOCEAN_ACCESS_TOKEN. The plan and apply commands check for this before calling tofu and exit early with instructions if neither variable is set.

Set the token directly:

export DIGITALOCEAN_ACCESS_TOKEN=dop_v1_...

Or pull it from an encrypted secrets file:

export DIGITALOCEAN_ACCESS_TOKEN=$(kb secrets decrypt .env.json | jq -r .DIGITALOCEAN_ACCESS_TOKEN)

Create a token at https://cloud.digitalocean.com/account/api/tokens.

Initialize OpenTofu

Download the DigitalOcean provider:

kb infra do init

This runs tofu init against tofu/remote/digitalocean/. Only needed on first use or after changing provider versions.

Configure variables

The Terraform configuration accepts variables that control cluster shape. The defaults are:

Variable	Default	Description
region	syd1	DigitalOcean region slug
node_size	s-1vcpu-2gb	Droplet size for worker nodes
node_count	3	Initial node count
auto_scale	true	Enable autoscaling
min_nodes	2	Autoscaling lower bound
max_nodes	4	Autoscaling upper bound
registry_name	rs-inc	Container registry name
maintenance_day	sunday	Maintenance window day
maintenance_start_time	04:00	Maintenance window start (UTC)

cluster_name is required and has no default. Pass it as a tofu variable. Create a terraform.tfvars file in tofu/remote/digitalocean/:

cluster_name = "my-cluster"
region       = "nyc3"
node_count   = 2

Plan

Preview what OpenTofu will create:

kb infra do plan

The plan creates three resources: a VPC (<cluster_name>-vpc), a container registry, and the DOKS cluster itself. The cluster version is resolved at plan time from the DigitalOcean API — this avoids state drift caused by the "latest" slug changing between plan and apply.

Apply

Create the infrastructure:

kb infra do apply

OpenTofu shows the plan and asks for confirmation. To skip the prompt:

kb infra do apply --auto-approve

Provisioning a new cluster takes several minutes. The cluster runs Kubernetes auto-upgrade and surge-upgrade, so node pool upgrades happen without downtime.

Retrieve kubeconfig

Once apply completes, write the cluster credentials to disk:

kb infra do kubeconfig

This reads the kubeconfig output from the tofu state and writes it to ~/.kube/do-cluster.conf with permissions 600. To write to a different path:

kb infra do kubeconfig --path ~/.kube/my-cluster.conf

Point kubectl at the new config:

export KUBECONFIG=~/.kube/do-cluster.conf
kubectl get nodes

List clusters

To see all DOKS clusters in your account with node pool specs and monthly pricing:

kb infra do clusters

Output format is human-readable by default. For scripting:

kb infra do clusters --json
kb infra do clusters --yaml

The clusters command calls doctl kubernetes cluster list and doctl compute size list in parallel, then computes per-pool and per-cluster monthly costs.

What gets created

A single apply provisions:

• A VPC named <cluster_name>-vpc in your chosen region
• A container registry (starter tier) with registry integration enabled on the cluster
• A DOKS cluster with the latest available Kubernetes version, auto-upgrade enabled, and a maintenance window on Sundays at 04:00 UTC

Destroying the cluster with kb infra do destroy --i-am-sure removes all three resources, including any workloads running in the cluster.