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), ECR, Route 53. Read Guide →
DigitalOcean	`digitalocean`	Droplets, App Platform, DOCR, DNS, block volumes.
Google Cloud	`gcp`	Cloud Run, Compute Engine, Artifact Registry, Cloud DNS.
Azure	`azure`	Virtual Machines, container workloads.

These are the only values accepted by infra.provider. In addition, Cloudflare is supported as a DNS-only provider via infra.dns: cloudflare (guide) — it is not a compute target.

[!NOTE] docker (local and SSH VPS) and aws are the most battle-tested paths. The digitalocean, gcp, and azure providers cover the full core flow, but parts of their end-to-end behavior are still in validation against live accounts.

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 →

[!NOTE] instances and other fleet/instance-group settings apply to VM / SSH compute (e.g. EC2). They do not apply to the serverless compute type — there autoscaling is driven by scaling, min, and max (see below).

Serverless Autoscaling (AWS ECS Fargate)

For the serverless compute type (AWS ECS Fargate), set scaling: auto with min and max to enable horizontal autoscaling per service:


infra:
  provider: aws
  region: us-east-1
  scaling: auto
  min: 1
  max: 5

When scaling: auto is set, Nanokit reconciles, for each app service:

An Application Auto Scaling scalable target on ecs:service:DesiredCount, bounded by min / max (defaults 1 / 3).
A CPU target-tracking policy that keeps the service’s average CPU utilization at 70% (ECSServiceAverageCPUUtilization).

Once autoscaling owns a service, Nanokit stops setting desiredCount directly so it never fights the autoscaler. Switching back to scaling: manual tears the scalable target and policy down again.

[!NOTE] System services (gateway, bridge) are never autoscaled — they stay at a single fixed task regardless of scaling. In manual mode, desiredCount falls back to min (default 1), or a per-service instances count when set.

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)