Provider Abstraction Layer (PAL)

Nanokit is designed to be infrastructure-agnostic. This is achieved through the Provider Abstraction Layer, a standardized interface that decouples the Core Engine from the specific details of cloud vendors or local runtimes.

The Provider Interface

Every infrastructure target (Docker, AWS, GCP, Azure) is implemented as a Provider. The Core Engine interacts with these providers using a unified set of methods defined in @nkapp/plugin-api.

Core Responsibilities

A Provider is responsible for:

Resource Discovery: Finding existing resources on the target platform.
Service Orchestration: Creating, starting, stopping, and deleting instances.
Health Monitoring: Verifying if a resource is ready to receive traffic.
Gateway Management: Configuring load balancers or entry points (e.g., Caddy, AWS ALB).

How it Works

When you run a command like nkapp up, Nanokit looks at the infra.provider field in your configuration:


infra:
  provider: aws   # Nanokit loads the AWS Provider plugin

The Core Engine then delegates all platform-specific operations to that plugin. This ensures that the same nanokit.yml can be used to deploy to a local Docker environment during development and to AWS during production.

Supported Providers

Nanokit includes first-party support for the roadmap.v1 provider set — these are the only values accepted by infra.provider and the only choices offered in the Hub:

Provider	Value	Target	Use Case
Docker	`docker`	Local Machine / VPS	Local development and simple server deployments (local socket or SSH-VPS).
AWS	`aws`	Amazon Web Services	Enterprise scaling using EC2 / ECS / Fargate, ECR, NLB, Route 53.
Azure	`azure`	Microsoft Azure	Virtual Machines, container services, and networking.
GCP	`gcp`	Google Cloud Platform	Cloud Run + Compute Engine, Artifact Registry, Cloud DNS.
DigitalOcean	`digitalocean`	DigitalOcean	Droplets + App Platform managed ingress, DOCR, VPC, volumes, DNS, metrics.

Cloudflare is DNS-only (infra.dns: cloudflare) — it manages DNS records but is not a compute target.

Removed providers. The former non-v1 placeholder packages — Hetzner, Linode, Railway, Vercel, Netlify, Fly.io, Scaleway, and the provider-nanokit scaffold — were ~4-LOC stubs with no working integration and have been removed from the repo. They are not selectable and adding any of them in the future means implementing a new provider package from scratch.

Extensibility: The PAL is plugin-based. Developers can write custom providers to support proprietary clouds or specialized hardware by implementing the Provider interface from @nkapp/plugin-api — the same contract every first-party provider uses.

Transparent Metadata

Providers automatically inject platform-specific metadata into your services (e.g., Instance IDs, Private IPs, Cluster names) using the NANOKIT_ environment variable prefix. This allows your application to be “Cloud Aware” without being “Cloud Dependent”.