Skip to Content
CLI Referencenkapp teardown

nkapp teardown

teardown [options]

Assertive Tag-Based Teardown: Direct, state-free remote infrastructure sweeping.

  • CI/CD Native: Specifically engineered for ephemeral CI/CD environments (like GitLab CI or GitHub Actions) where local state files (.nanokit/) are missing or out of sync.
  • Tag-Based Discovery: Directly queries cloud provider APIs (AWS, DigitalOcean, etc.) via resource tags (nk-project and nk-env) to discover and forcefully destroy all related project resources.
  • Zero Orphaned Resources: Bypasses any local metadata tracking, serving as a bulletproof safety net against cloud billing leaks and orphaned compute/storage instances.
nkapp teardown [options]

Options

FlagTypeDefaultDescription
-p, --project <project>string(resolves from config)Target project name
-e, --env <env>stringstageTarget environment name
--provider <provider>string(resolves from config)Force target provider (e.g. aws, digitalocean)
-r, --region <region>string(env’s configured region)Sweep a single cloud region only
--all-regionsbooleanfalseForce the full multi-region sweep (state-free orphan hunt; slower)
-y, --yesbooleanfalseBypass confirmation prompts (essential for CI/CD pipelines)
--forcebooleanfalseContinue sweeping even if intermediate API calls fail

Region Scope (AWS)

By default, teardown (and nkapp clean) on AWS now sweep only the environment’s configured region — resolved from the env’s deploy target, or the provider’s default region. Resources are deployed exclusively to that region, so the old full multi-region sweep (~17 regions) was wasteful and slow.

  • --region <r> targets one specific region (overriding the resolved one).
  • --all-regions forces the full sweep across every active region. This is the state-free orphan hunt for the case where the region cannot be resolved (e.g. no nanokit.yml in an ephemeral CI runner) — the sweep then falls back to all regions automatically. The configured region is always included even if AWS omits it from DescribeRegions (opt-in regions).

Why Teardown is Crucial for CI/CD

Standard cleanup commands like nkapp destroy or nkapp clean rely on local configuration parses and state tracking databases (services-state.json) to know what exists and what needs to be destroyed.

In ephemeral CI/CD pipelines:

  1. The build runner spins up on a fresh, clean docker container.
  2. The local .nanokit/ directory is empty.
  3. Running nkapp clean has zero knowledge of what instances were previously spun up by another job. It sees no state files and exits with no action, leaving active instances running on your cloud account!

nkapp teardown solves this by bypassing the local state completely. It logs directly into the cloud provider (AWS / DigitalOcean), queries the active resource registry for all objects tagged with nk-project:<project> and nk-env:<env>, and wipes them from existence.

Feature Comparison

CommandState-Independent?Destroys Instances?Destroys Volumes?Primary Target
nkapp destroy❌ No (requires local state)✅ Yes❌ NoLocal & Cloud Services
nkapp clean❌ No (requires local state)✅ Yes✅ YesComplete Local Wipe
nkapp teardown✅ Yes (Queries APIs directly)✅ Yes✅ YesAssertive Cloud Pruning

Sweeping Behavior by Provider

DigitalOcean Provider

When executed against DigitalOcean, the teardown sweeps:

  • Droplets: Forcefully destroys any active compute Droplets tagged with nk-project:<name> and nk-env:<env>.
  • App Platform: Scans and prunes App Platform deployments matching the project.
  • Block Storage Volumes: Actively sweeps and purges any detached or attached block storage volumes containing ${projectName}-${envName} in their name (e.g. database persistent mounts or docker system volumes).

AWS Provider

When executed against AWS, the teardown sweeps:

  • EC2 Instances: Forcefully terminates tagged instances.
  • VPC & Subnets: Detaches and deletes tagged Elastic IPs, Internet Gateways, Subnets, and associated ENIs (Network Interfaces) once settled.
  • ELB/ALB/NLB: Scans and destroys active Application/Network Load Balancers and associated Target Groups.
  • EFS File Systems: Terminates and purges tagged storage systems.

Examples

# Forcefully tear down staging environment in CI/CD without prompts
nkapp teardown -p my-project -e stage -y
 
# Perform teardown on a specific provider with forced execution
nkapp teardown -p core-app -e dev --provider digitalocean -y --force

[!WARNING] nkapp teardown is an extremely assertive, destructive command that directly manipulates remote resources. It ignores any safety locks inside local state registries. Always verify your -p (project) and -e (env) targets before execution.

nkapp teamnkapp up