README
¶
Nstance: Fast, Cloud-Agnostic VM Auto-Scaler
Nstance is a faster alternative to traditional Auto-Scaling Groups (ASGs), replacing glue scripts and complexity with a cloud-agnostic VM provisioner.
Nstance is Open Source, released under the Apache 2.0 license.
Key features:
-
Faster instance scaling: Provision Kubernetes nodes faster than traditional bootstrap and certificate workflow methods.
-
Not just for Kubernetes: Agnostic design for any workload e.g. Docker Compose VMs, NAT gateways, and more.
-
Multi-Cloud & Hybrid-Cloud: Supports public cloud (AWS, Google Cloud) and on-prem/private cloud (Proxmox VE).
-
Self Healing & Instance Expiry: Automatic detection and replacement of unhealthy instances. Automatic rotation with configurable expiry.
-
Built-in CA: Integrated certificate authority for fast and secure certificate issuance and renewal/rotation.
-
Spot Instance Support: With Kubernetes node draining and termination handling.
-
Kubernetes Auto-Scaling: Nstance includes its own Operator and CRDs which enables integration with the Cluster Autoscaler via Cluster API.
-
On-Demand Instances: Using Kubernetes Pod annotations, the Nstance Operator will create a new dedicated VM for the lifetime of the Pod.
-
Multi-Tenancy: Run one or more Kubernetes clusters with isolation on each Nstance cluster.
Nstance is designed to be simple and easy to operate. To achieve a balance of lowest cost, highest reliability, and easiest operation, Nstance uses simple yet proven cloud primitives - VMs (and optionally, ASGs), a secrets store (such as AWS Secrets Manager), and object storage (such as AWS S3, Google Cloud Storage, or S3-compatible services supporting If-Match headers such as Ceph RGW or SeaweedFS).
Documentation
Check out the comprehensive documentation in ./docs or read it rendered on the official Nstance website at https://nstance.dev
Development
See docs/development/local-setup.md for development environment setup and usage.
License
Nstance is licensed under the Apache License, Version 2.0. Copyright 2026 Nadrama Pty Ltd.
See the LICENSE file for details.
Directories
¶
| Path | Synopsis |
|---|---|
|
api
|
|
|
v1beta1
Package v1beta1 contains API Schema definitions for the infrastructure v1beta1 API group +kubebuilder:object:generate=true +groupName=infrastructure.cluster.x-k8s.io
|
Package v1beta1 contains API Schema definitions for the infrastructure v1beta1 API group +kubebuilder:object:generate=true +groupName=infrastructure.cluster.x-k8s.io |
|
cmd
|
|
|
dev-k8s
command
Package main implements a lightweight fake Kubernetes API server for development.
|
Package main implements a lightweight fake Kubernetes API server for development. |
|
dev-s3
command
|
|
|
nstance-admin
command
|
|
|
nstance-agent
command
|
|
|
nstance-operator
command
|
|
|
nstance-server
command
|
|
|
internal
|
|
|
admin/cmd
Package cmd implements the CLI commands for nstance-admin.
|
Package cmd implements the CLI commands for nstance-admin. |
|
admin/server
Package server provides the HTTP API server for nstance-admin.
|
Package server provides the HTTP API server for nstance-admin. |
|
admin/service
Package service provides the core business logic for nstance-admin operations.
|
Package service provides the core business logic for nstance-admin operations. |
|
agent/cmd
Package cmd implements the nstance-agent command entry point and lifecycle management.
|
Package cmd implements the nstance-agent command entry point and lifecycle management. |
|
agent/config
Package config provides configuration loading and validation for the nstance-agent.
|
Package config provides configuration loading and validation for the nstance-agent. |
|
agent/keygen
Package keygen implements key generation request handling for the nstance-agent.
|
Package keygen implements key generation request handling for the nstance-agent. |
|
agent/receiver
Package receiver handles secure file receicing and validation for the nstance-agent.
|
Package receiver handles secure file receicing and validation for the nstance-agent. |
|
buildvars
Package buildvars provides build-time information such as version, commit hash, and date.
|
Package buildvars provides build-time information such as version, commit hash, and date. |
|
files
Package files provides utilities for handling and validating files like PEM, JWT, etc.
|
Package files provides utilities for handling and validating files like PEM, JWT, etc. |
|
identifiers
Package identifiers provides validation helpers for Nstance identifier formats.
|
Package identifiers provides validation helpers for Nstance identifier formats. |
|
identity
Package identity provides agent identity management and certificate generation utilities.
|
Package identity provides agent identity management and certificate generation utilities. |
|
operator/config
Package config provides configuration loading for the nstance-operator from Kubernetes secrets and environment.
|
Package config provides configuration loading for the nstance-operator from Kubernetes secrets and environment. |
|
operator/connection
Package connection manages persistent gRPC connections to nstance-server zone shards.
|
Package connection manages persistent gRPC connections to nstance-server zone shards. |
|
operator/controller
Package controller implements Kubernetes controllers for NstanceCluster, NstanceMachine, NstanceMachinePool, and on-demand Pods.
|
Package controller implements Kubernetes controllers for NstanceCluster, NstanceMachine, NstanceMachinePool, and on-demand Pods. |
|
operator/drain
Package drain provides graceful node draining and workload eviction for the nstance-operator.
|
Package drain provides graceful node draining and workload eviction for the nstance-operator. |
|
operator/leader
Package leader manages operator runtime orchestration including registration, connections, state sync, and node draining.
|
Package leader manages operator runtime orchestration including registration, connections, state sync, and node draining. |
|
operator/node
Package node provides utilities for resolving cloud provider instance IDs to Kubernetes Nodes.
|
Package node provides utilities for resolving cloud provider instance IDs to Kubernetes Nodes. |
|
operator/sync
Package sync provides synchronization between Kubernetes CAPI and Nstance* resources and each nstance-server's groups/instances.
|
Package sync provides synchronization between Kubernetes CAPI and Nstance* resources and each nstance-server's groups/instances. |
|
operator/webhooks
Package webhooks provides validating admission webhooks for Nstance CRDs.
|
Package webhooks provides validating admission webhooks for Nstance CRDs. |
|
proto
Package proto contains generated Protocol Buffer types for nstance gRPC services.
|
Package proto contains generated Protocol Buffer types for nstance gRPC services. |
|
renewal
Package renewal provides operator client certificate renewal logic for long-running processes.
|
Package renewal provides operator client certificate renewal logic for long-running processes. |
|
server/api
Package api provides the main gRPC server and shared authentication logic.
|
Package api provides the main gRPC server and shared authentication logic. |
|
server/api/agent
Package agent provides the Agent gRPC service implementation.
|
Package agent provides the Agent gRPC service implementation. |
|
server/api/operator
Package operator provides the Operator gRPC service implementation.
|
Package operator provides the Operator gRPC service implementation. |
|
server/api/registration
Package registration provides the Registration gRPC service implementation.
|
Package registration provides the Registration gRPC service implementation. |
|
server/cluster
Package cluster provides cluster-level coordination including leader election.
|
Package cluster provides cluster-level coordination including leader election. |
|
server/cmd
Package cmd implements the nstance-server command entry point and lifecycle management.
|
Package cmd implements the nstance-server command entry point and lifecycle management. |
|
server/config
Package config provides configuration loading and validation for the nstance-server.
|
Package config provides configuration loading and validation for the nstance-server. |
|
server/election
Package election provides a unified manager for cluster and shard leader elections, abstracting the s3lect library and serving both election health endpoints from a single HTTPS server.
|
Package election provides a unified manager for cluster and shard leader elections, abstracting the s3lect library and serving both election health endpoints from a single HTTPS server. |
|
server/filegen
Package filegen generates required certificates and keys for instances.
|
Package filegen generates required certificates and keys for instances. |
|
server/gc
Package gc provides periodic garbage collection and maintenance tasks for nstance instances.
|
Package gc provides periodic garbage collection and maintenance tasks for nstance instances. |
|
server/health
Package health provides HTTP health check endpoints for ASG and load balancer integration.
|
Package health provides HTTP health check endpoints for ASG and load balancer integration. |
|
server/images
Package images provides periodic image resolution and caching across infrastructure providers.
|
Package images provides periodic image resolution and caching across infrastructure providers. |
|
server/infra
Package infra provides infrastructure provider abstraction and factory.
|
Package infra provides infrastructure provider abstraction and factory. |
|
server/infra/aws
Package aws provides AWS EC2 and load balancer implementation of the infrastructure provider interface.
|
Package aws provides AWS EC2 and load balancer implementation of the infrastructure provider interface. |
|
server/infra/gcp
Package gcp provides Google Cloud Compute Engine implementation of the infrastructure provider interface.
|
Package gcp provides Google Cloud Compute Engine implementation of the infrastructure provider interface. |
|
server/infra/mock
Package mock provides a test mock implementation of the infrastructure provider interface.
|
Package mock provides a test mock implementation of the infrastructure provider interface. |
|
server/infra/provider
Package provider defines the infrastructure provider interface for instance and load balancer operations.
|
Package provider defines the infrastructure provider interface for instance and load balancer operations. |
|
server/infra/proxmox
Package proxmox implements the Nstance provider interface for Proxmox VE.
|
Package proxmox implements the Nstance provider interface for Proxmox VE. |
|
server/infra/tmux
Package tmux provides local development implementation of the infrastructure provider interface using tmux.
|
Package tmux provides local development implementation of the infrastructure provider interface using tmux. |
|
server/instances
Package instances orchestrates instance lifecycle: generating IDs, registration nonce JWTs, and userdata, then delegating VM creation to the infra package.
|
Package instances orchestrates instance lifecycle: generating IDs, registration nonce JWTs, and userdata, then delegating VM creation to the infra package. |
|
server/keys
Package keys provides cryptographic key parsing and handling utilities.
|
Package keys provides cryptographic key parsing and handling utilities. |
|
server/localdb
Package localdb provides database models and operations for local nstance-server state.
|
Package localdb provides database models and operations for local nstance-server state. |
|
server/pki
Package pki provides certificate and key generation for instance PKI.
|
Package pki provides certificate and key generation for instance PKI. |
|
server/reconciler
Package reconciler provides infrastructure state reconciliation driven by event queue processing.
|
Package reconciler provides infrastructure state reconciliation driven by event queue processing. |
|
server/secrets
Package secrets provides encrypted secret storage using pluggable backends.
|
Package secrets provides encrypted secret storage using pluggable backends. |
|
server/storage
Package storage provides an abstraction for object storage operations.
|
Package storage provides an abstraction for object storage operations. |
|
pkg
|
|
|
client/agent
Package agent provides a gRPC client for agent services.
|
Package agent provides a gRPC client for agent services. |
|
client/registration
Package registration provides a gRPC client for agent and operator registration with nstance-server.
|
Package registration provides a gRPC client for agent and operator registration with nstance-server. |
|
health
Package health provides system health metrics collection and reporting.
|
Package health provides system health metrics collection and reporting. |
|
instanceinfo
Package instanceinfo provides cloud instance metadata provider interface and implementations.
|
Package instanceinfo provides cloud instance metadata provider interface and implementations. |
|
topsis
Package topsis implements the TOPSIS (Technique for Order of Preference by Similarity to Ideal Solution) multi-criteria decision analysis algorithm, used e.g.
|
Package topsis implements the TOPSIS (Technique for Order of Preference by Similarity to Ideal Solution) multi-criteria decision analysis algorithm, used e.g. |
Click to show internal directories.
Click to hide internal directories.