Platform Teardown

Getting Started

Irreversible Action

The teardown process is permanent for your data. All records stored in BigTable or other storage components will be lost. Ensure you have backups before proceeding.

This guide provides a structured process for decommissioning a Nexus SDV instance. Using the automated teardown-platform.sh script, you can securely remove infrastructure while having the option to preserve specific core components for future use. To go ahead, all you have to do is follow these steps:

1. Verify Identity Ensure you are using the same Google Cloud project and GitHub repository that was used for the initial bootstrapping.

2. Execute Teardown Run the decommissioning script from your terminal: bash ./iac/bootstrapping/teardown-platform.sh

3. Verify Cleanup Confirm that the resources have been removed from the GCP Console and your environment is in the desired state.

Avoid State Lock Errors

It is strongly recommended that the same operator who performed the bootstrapping also executes the teardown. This ensures consistent access to the Terraform state and avoids permission issues or state lock errors.

Prerequisites

The teardown process requires the same environment stability as the deployment.

Required Command Line Interfaces (CLIs)

Ensure these tools are installed and authenticated before starting:

Tool	Purpose
Google Cloud CLI (gcloud)	Removing GCP resources and Secret Manager entries.
Terraform CLI (terraform)	Executing the terraform destroy command for infrastructure removal.
GitHub CLI (gh)	Deleting environment variables and cleaning up repository states.
jq (jq)	Processing JSON-based environment data from GitHub.

Launching the Script

To initiate the decommissioning, execute the script from the project’s root directory:

$ bash iac/bootstrapping/teardown-platform.sh

Authentication

The script will attempt to log you into GCP and GitHub again. Keep your browser ready to confirm the login requests to obtain the necessary access tokens for the destruction of resources.

Required User Inputs

In case a GitHub driven deployment was used, the script will prompt you for these inputs:

1. GitHub Repository Notation (GITHUB_REPO): e.g., owner/repo.
2. GitHub Environment (ENV): The name used during bootstrap (max. 15 chars).

Preservation & Recommendations

During the process, the script will ask whether to delete or preserve specific resources. For PoC environments, we recommend a “soft” teardown:

CA Pools (Remote Strategy only)

The script asks if you want to preserve your Certificate Authority Pools.

• Recommendation: Preserve them (Type ‘y’).
• Why: GCP CA Pools have a 30-day recovery period. Keeping them prevents naming conflicts and makes redeploying the platform much faster and more resource-efficient.

The .bootstrap_env File

At the end, you are asked whether to delete the local configuration file.

• Recommendation: Do NOT delete (Type ‘n’).
• Why: This file contains your project configuration. Keeping it allows you to restart the platform later without re-entering all IDs and regions.

The Decommissioning Flow

Once started, the script performs a coordinated cleanup across three main layers:

1. Manual Resource Cleanup

Specific resources, such as GKE workloads, are terminated first to ensure a clean state and free up database connections.

2. Infrastructure Destruction (Terraform)

The script executes terraform destroy. This removes the GKE cluster, BigTable instances, and networking components. Note that CA pools and APIs are often removed from the state instead of being deleted to avoid recovery locks.

3. State & Environment Removal

In the final stage, the script:

• Deletes the Cloud Storage bucket containing the Terraform state.
• Clears non-essential GitHub Environment variables.
• Wipes entries from the GCP Secret Manager.

Verifying Teardown Success

A successful teardown is confirmed by the following message:

$ bash iac/bootstrapping/teardown-platform.sh
...
[INFO] ==================================================================
[INFO]   🎉 Nexus SDV platform teardown successfully completed! 🎉
[INFO] ==================================================================
[INFO] Your Google Cloud project environment is now empty again.
[INFO] Local files have been cleaned up.

Final Manual Check

Service	Expected State
GKE	No active clusters related to the environment.
Cloud Storage	The [gcp-project-name]-tfstate bucket has been removed.
Secret Manager	Environment-specific secrets are deleted.

Terraform State Lock Error

A bootstrap or teardown stops with:

Error: Error acquiring the state lock

Lock Info:
  ID:        1762856907718990
  Operation: OperationTypeApply
  Who:       root@a1b2c3d4e5f6
  Created:   2026-10-01 09:14:22.481 +0000 UTC

Terraform keeps your platform’s state in a Cloud Storage bucket and locks it while it changes infrastructure, so that two runs cannot write at the same time. The lock is released when the run ends.

The usual cause is a run that did not end. A build cancelled by hand, a build that hit its timeout, or a session closed mid-apply leaves the lock behind with nobody holding it. Every later run then waits — the teardown waits 60 seconds — and fails.

The second cause is genuine concurrency: a bootstrap and a teardown for the same platform, or two people, at the same time.

Before you unlock

Make sure nothing is actually running. Unlocking a live operation lets a second run write the same state and can leave your platform in a state Terraform can no longer describe.

gcloud builds list --project=<GCP_PROJECT_ID> --region=<GCP_REGION> --ongoing

If that lists a bootstrap or teardown, wait for it. If it is empty, and nobody is running Terraform from their own machine, the lock is stale.

Caution

force-unlock only removes the lock. It never rolls back a half-finished change, so if the previous run was interrupted, check your project for resources it had already created before starting again.

Releasing the lock

Take the ID from the error and release the lock from the same directory and the same backend configuration the run used:

cd iac/terraform
terraform init -backend-config="bucket=<STATE_BUCKET>" -backend-config="prefix=<ENV>"
terraform force-unlock 1762856907718990

The init is needed: force-unlock acts on the configured backend, and a fresh checkout has none. The bucket and prefix are the values the bootstrap used for this environment — your .bootstrap_env has them.

Then start the operation again.