Platform Deployment

Understanding the Deployment Flow

This guide is designed for Nexus admins and engineers conducting Proof of Concepts (PoCs). By automating environment configuration, infrastructure provisioning, and service deployment, it streamlines the bootstrapping process—allowing you to stand up a fully functional platform instance in minutes through the following steps:

1. Prepare Environment Configure your local machine with the required CLI tools (gcloud, terraform, kubectl).

2. Execute Bootstrap Run the deployment script from your terminal: bash ./iac/bootstrapping/bootstrap-platform.sh

3. Verify Deployment Confirm the success of the installation in your local terminal and the GCP Console.

Deployment in a Nutshell

The setup process is driven by a single, unified bootstrapping script. This script authenticates with your target GCP project to provision the entire infrastructure.

Starting with v1.1.0, we recommend utilizing GCP Cloud Build as the primary deployment engine. Unlike GitHub Actions, this native approach requires no external dependencies or third-party integrations beyond your locally cloned repository and your GCP environment. This “sovereign-first” integration significantly reduces setup complexity and provides a robust foundation for fully automated, headless CI/CD deployments.

The Nexus v1.1.0 deployment follows a Dispatcher-Model that strictly separates infrastructure provisioning from software orchestration:

• Local Operator Machine: Your local machine acts as the command center. The bootstrap-platform.sh script controls Terraform to provision the core “hardware” (GKE clusters, networking, and BigTable) directly into your GCP project. It also serves as the trigger for the cloud-native software rollout.
• GCP Project Infrastructure: Once the infrastructure is ready, GCP Cloud Build takes over. Running natively within your project boundaries, it provisions the software layer (Helm charts and Kubernetes workloads) using the internal service accounts.

Why Cloud Build over GitHub Actions?

While Nexus still supports GitHub Actions, the Cloud Build approach is recommended for v1.1.0+:

1. Security: No need to store sensitive GCP Service Account keys as GitHub Secrets. All credentials stay within your Google Cloud IAM boundary.
2. Simplicity: You don’t need to configure GitHub OIDC providers or Personal Access Tokens (PATs).
3. Connectivity: Since the builder runs inside your GCP project, it has native, high-speed access to your GKE cluster without crossing the public internet.

---

Prerequisites and Setup

Before running the bootstrapping script, ensure your repository and local environment are prepared.

Repository Setup

1. Fork the Repository: Fork the official Nexus SDV repository into your own (private) GitHub account.
2. Clone Locally: Clone your fork to the machine from which you will run the deployment.

Local Environment & Shell

The bootstrapping script is developed and best tested for the Bash shell. While other shells might work, we recommend using Bash for the most stable experience.

Required Command Line Interfaces (CLIs)

The following tools must be installed and available in your $PATH:

Tool	Purpose
Google Cloud CLI	Authentication and GCP resource management.
Terraform CLI	Provisioning the Cloud Infrastructure (IaC).
OpenSSL	Generation of secure tokens and secrets.
Nk	Creating NKeys for NATS communication authentication.
GitHub CLI (gh)	Optional: needed only, for GitHub driven installations. Managing repository variables and triggering Actions.

Launching the Script

Execute the bootstrap-platform.sh script from the project’s root directory to initially set up the platform:

$ bash iac/bootstrapping/bootstrap-platform.sh

The script will check whether all necessary prerequisites have already been installed. If not, the script will output a list with all missing tools to be installed and break.

Pre-Authentication (Recommended)

While the script includes an authentication check, we recommend logging in manually before execution to ensure all CLI tools have the necessary permissions:

1. GCP CLI Access: gcloud auth login
2. Terraform Access (ADC): gcloud auth application-default login

This is particularly helpful when performing the deployment from within a GCP VM (e.g., a Compute Engine instance) to ensure the environment is correctly scoped for the bootstrapping process. The script will automatically detect your existing session and proceed without further interruption.

Querying User Inputs

After authentication, the script will prompt you for the following configuration data to set up your environment:

1. Google Cloud Project ID (GCP_PROJECT_ID): The ID of the GCP project where the platform will be deployed.
2. Google Cloud Region (GCP_REGION): The target region for your infrastructure (e.g., europe-west3).
3. GitHub Repository Notation (GITHUB_REPO): Optional (required for GitHub-driven deployments): Your forked repository in the format owner/repo.
4. Environment Identifier (ENV): This name is used to prefix and isolate your GCP infrastructure services (e.g., dev, prod). For GitHub-driven deployments, this must match the name of the Environment to be created or reused within your GitHub project.
5. GKE Compute Architecture (ARCH): Defines the CPU architecture for the GKE node pools.
   • amd64: Uses standard x86 instances (e.g., e2-standard-4).
   • arm64: Uses Google Cloud Tau T2A instances for optimized cost-performance.
   • Important: Ensure your selected GCP_REGION supports GKE on ARM64 and the availability of Tau T2A instances before proceeding.
6. Setup Strategy (PKI_STRATEGY): Defines the handling of the Public Key Infrastructure. Use local for rapid prototyping or remote for production-mirroring scenarios (see the PKI section below for details).

Naming Conventions

To ensure a smooth Terraform apply, the ENV value must be strictly alphanumeric (lowercase, no special characters or spaces). If the input exceeds 12 characters or contains invalid characters, the infrastructure provisioning could fail.

For GitHub-driven deployments, the script will create a new environment in GitHub to store deployment attributes. If an environment with the same name already exists, it will be overwritten to prevent errors during the configuration of environment variables. Note that only variables are used, no GitHub secrets.

Setup Strategies: Local vs. Remote

For your first deployment, we recommend starting with the Local strategy.

Local Setup (Recommended)

The Local strategy is the fastest way to get started. It uses IP addresses instead of DNS names and relies on self-signed certificates.

• Pros: Rapid setup, no DNS or CA configuration required.
• Cons: Limited to IP-based communication; no custom domain support.

Remote Setup (Advanced)

The Remote strategy is designed for production-like environments. It leverages Google Cloud DNS and the GCP Certificate Authority Service (CAS) to establish a managed, scalable Chain of Trust.

Prerequisites:

• A registered DNS Domain and an active Cloud DNS Zone within your Google Cloud project.

Interactive Setup: The deployment script will guide you through an interactive dialog to capture your configuration. Key parameters include:

PKI_STRATEGY="remote"
BASE_DOMAIN="nexus.your-oem-domain.com"
EXISTING_DNS_ZONE="nexus-your-oem-domain-com"

Beyond these, the script will prompt for additional environment-specific details, such as endpoint hostnames, CA and CA-pool identifiers. All inputs are persisted in your .bootstrap_env for future reference.

⚠️ Critical: Backup your .bootstrap_env The values captured in this file are essential for a successful teardown. Without it, the script cannot cleanly decommission managed resources like CA Pools and DNS records. Always keep a secure backup.

Automated Infrastructure Output: Nexus handles the complexity of production setups automatically. The script:

• Provisions Managed CAs: Creates GCP CA Pools and Sub-CAs based on your inputs.

• Writes Metadata: Automatically exports all generated identifiers back into the .bootstrap_env.

• DNS Orchestration: Sets up the necessary A-records and managed zones.

• Pros: Full mTLS with managed CAs, professional DNS endpoints, production-grade security.

---

Automated Launch with an Env-file

To skip the interactive dialogues and provide the required inputs automatically, you can create a configuration file named .bootstrap_env.

Placement: Save this file in the iac/bootstrapping/ directory. The script will automatically detect these variables and bypass the manual prompts.

Example .bootstrap_env for Local Setup:

GCP_PROJECT_ID="nexus-sdv-demo"
GCP_REGION="europe-west3"
DEPLOY_MODE="cloudbuild"
ENV="demo"
PKI_STRATEGY="local"
ARCH="arm64"

Automated Provisioning & Deployment

Now that the configuration is set, you can relax and monitor the progress in your console. The bootstrapping script will handle the heavy lifting across your GCP project and GitHub repository in a coordinated sequence:

Time for a Coffee

Provisioning the full infrastructure stack can take up to 20 minutes. The creation of the Cloud SQL database for Keycloak typically accounts for the largest portion of this duration.

What is happening in the background?

The deployment follows a three-stage execution flow:

1. Infrastructure Provisioning (Terraform): Essential Google Cloud resources are set up using Terraform. This includes the API activation, the Terraform state bucket, and the core infrastructure components.

2. Configuration & Security Mapping: In between the main steps, the script creates GitHub environment variables within your specified repository and stores secrets within the Google Cloud Secret Manager. This stage is essential for establishing the automatic deployment flow and managing platform keys for mutual TLS (mTLS) and CA registration.

3. Software Deployment (GCP Cloud Build or GitHub Actions): Once the foundation is secure, the platform’s base services are deployed via GitHub Actions pipelines. These components are automatically distributed to their target runtimes on Google Cloud Run and Google Kubernetes Engine (GKE).

Verifying Deployment Success

Once the bootstrapping script completes its execution, you should see a confirmation in your terminal accompanied by several green success indicators.

Terminal and GitHub Confirmation

A successful deployment is characterized by the following outputs:

• Terminal: The script will print Nexus SDV platform bootstrapping successfully completed! along with celebratory emojis.

• GCP Cloud Build: navigate to Cloud Build > History in your GCP Console. You should see a “Successful” build containing all 9 orchestration steps (e.g., deploy-keycloak, deploy-nats, build-push-deploy-registration).

• GitHub Actions: For GitHub-driven deployments, the “Deploy Platform” workflow in your forked repository should show a green “Success” status. You can verify the individual jobs and logs in the Actions tab.

Manual ‘Smoke Check’ in GCP

To ensure all infrastructure components are correctly provisioned, log in to your Google Cloud Console and verify the following:

Service	Expected Resource
Cloud Storage	A bucket named [gcp-project-name]-tfstate containing the default.tfstate file.
Kubernetes Engine	A GKE cluster named [env]-gke with healthy, running pods. This hosts the Nexus base services (Status: Green).
BigTable	An active BigTable instance named bigtable-production-storage ready for data ingestion.

Technical Deep Dive

For a complete list of all provisioned resources, you can always refer to the Terraform configuration files located in the iac/terraform directory of your repository.

Platform Output & Connectivity

In a Local Setup, the platform relies on IP addresses.

• IP Addresses: Check the script output for the assigned external IP addresses of your GKE services.
• Sample Client: You can find initial connectivity tests in the sample-client folder.

Note

A detailed guide on how to use the Sample Client to interact with your new Nexus SDV instance will be covered in the next section of this documentation.