Infrastructure (`infra`)

The infra block defines the provisioning layer. Nanokit abstracts cloud-specific complexity while allowing you to tap into advanced networking and scaling features.

Target Providers

Provider	ID	Capabilities
Local / VPS	`docker`	Standard Docker Engine. Used for local dev and SSH VPS.
AWS	`aws`	EC2, ECS (Fargate), EKS, RDS. Read Guide →
DigitalOcean	`digitalocean`	Droplets, DOKS, App Platform.
Google Cloud	`gcp`	Cloud Run, GKE.
Azure	`azure`	Virtual Machines, AKS.
Specialized	`hetzner`, `scaleway`, `linode`	Bare-metal and Cloud VMs.
Serverless	`vercel`, `netlify`, `railway`, `fly.io`	Edge functions and microVMs.

Networking & VPC

For secure and high-performance cross-service communication, Nanokit allows direct attachment to existing virtual networks.

Property	Type	Description
`vpc`	string	The identifier of an existing Cloud Virtual Private Cloud (VPC).
`cidr`	string	Custom IP range in CIDR notation (e.g., `10.0.0.0/16`) for auto-provisioned networks.

Instances & Scaling

Property	Type	Description
`scaling`	`manual` \| `auto`	Scaling logic. `auto` requires cloud-level metrics support.
`min`	number	Minimum number of global infrastructure instances.
`max`	number	Maximum number of global infrastructure instances.
`instances`	Object[]	Collection of machine definitions (fields: `type`, `count`, `role`).
`dns`	`aws` \| `digitalocean` \| `cloudflare` \| `gcp`	Cloud DNS provider for automated record management.
`autoCreateDomain`	boolean	If `true`, Nanokit automatically registers or configures the target domain.
`shared`	boolean	If `true`, Nanokit adopts existing infrastructure without creating or modifying it. Used in multi-repo setups. Read Guide →

Example: Multi-region AWS Setup (VPC)


infra:
  provider: aws
  region: us-east-1
  vpc: vpc-0a1b2c3d4e5f
  scaling: auto
  instances:
    - type: t3.medium
      count: 2
      role: manager

[!TIP] Zero-Config Routing: If no VPC is provided, Nanokit automatically creates an isolated Docker network (or cloud equivalent) for your environment.

Multi-Repo & Shared Clusters

Use the component field (at the top level of nanokit.yml) and infra.shared: true to deploy multiple repositories onto the same cluster without accidental cross-repo resource deletion.

→ Multi-Repo & Shared Clusters Guide

Troubleshooting

Stale Deployment Locks

If a deployment or provisioning cycle is interrupted (e.g., network failure, manual stop), a lock file might remain on the shared volume or in the remote state store. This will block subsequent deployments with a “Shared modules are being initialized…” message.

To resolve this, use the Unlock command:


nkapp infra unlock --env local

This will safely clear the stale lock and allow the next reconciliation loop to proceed.

Infrastructure (infra)