Platform Engineering Starter Kit Series: Introduction and Prerequisites (1)

When you’re starting a small project or early-stage startup, it’s common to think:

“I know I need DevOps… but where do I even start?”
“Do I set up a pipeline first? Or infrastructure? How do I deploy?”

This series is my opinionated Platform Starter Kit — a reusable, production-grade setup running on Google Cloud with Terraform, Helm, Argo CD, and GitHub Actions. It’s designed for small teams who want a strong foundation without reinventing the wheel.

You can browse or clone the completed code for this post here:
🔗 post-01-intro-prerequisites

What You’ll Build in the Series

By the end of this series, you’ll have:

• Terraform for infrastructure provisioning (GKE, VPC, service accounts)
• Helm + GitOps (Argo CD) for app deployment
• GitHub Actions for CI/CD pipelines
• Prometheus, Grafana, and Loki for monitoring
• Secrets management via SOPS or External Secrets Operator
• FastAPI + React templates for apps
• A developer-friendly Makefile and CLI wrapper

Final directory structure:

platform-starter-kit/
├── .env.sample                # Template only (committed)
├── .env.dev                   # Dev local settings (gitignored)
├── .env.staging               # Staging local settings (gitignored)
├── .env.prod                  # Prod local settings (gitignored)
├── terraform/                 # Infra modules (GKE, VPC, IAM)
│   └── gcp/
├── helm/                      # Helm charts for platform components
├── argocd/                    # Argo CD GitOps app manifests
├── .github/workflows/         # CI/CD pipelines (build/test/deploy)
├── templates/                 # FastAPI + React starter templates
├── platform-cli/              # Optional Bash/Go wrapper CLI
├── Makefile                   # Self-service commands
└── docs/                      # Setup, usage, and architecture docs

Prerequisites

If you’re on Windows, I recommend using WSL2 (Ubuntu) for this project.

Refer to my guide:
Developing with WSL on Windows — How it Works and How to Use It Effectively

Before jumping in, make sure you have the following ready on your system:

1. Git + GitHub Account

• Install Git
• Create a GitHub account

Then set up your project repository:

• Go to https://github.com/new
• Name your repo something like platform-starter-kit
• Clone it locally:

git clone https://github.com/<your-username>/platform-starter-kit.git
cd platform-starter-kit

2. Google Cloud Account, Project, Security

2.1 Sign in / Sign up

• Sign up or log in at Google Cloud Console
• If new, you may get $300 credits for 90 days — but charges can still happen after that

2.2 Turn on 2-Step Verification + Authenticator

Go to Google Account Security, under How you sign in to Google

• Enable 2-Step Verification
• Add Authenticator app (scan QR, confirm a code)

2.3 Create a GCP Project

• In the GCP Console, click the project selector at the top (next to the Google Cloud logo)

• Click New Project

• Name it something like platform-starter-kit and click Create
• After it’s created, click the bell (Notifications) → Select Project to make it active

2.4 Link a Billing Account

• Use the search bar → Billing
• If prompted, link your billing account and set it as default for your project

2.5 Set a Budget & Alerts

Even if you’re on free trial credits, budget alerts help prevent surprises.

1. Go to Billing → Budgets & alerts → CREATE BUDGET
2. Select your billing account and platform-starter-kit project
3. Set a monthly budget (e.g., usually $20–50 for dev experiments but I’ll set the budget to $1 — since I’m on the free tier, this will alert me almost instantly if any charges start accruing.)
4. Add alerts at 50% and 90% usage
5. Save

3. Enable Required APIs

In the Console:

1. Search for APIs & Services → Enable APIs and Services
2. Enable:

• Kubernetes Engine API
• Compute Engine API
• Artifact Registry API
• Cloud Resource Manager API
• IAM Service Account Credentials API
• Service Usage API
• Cloud Build API (optional, useful for CI builds later)
• Cloud Key Management Service (KMS) API (Optional, for later posts, for SOPS + GCP KMS)
• Secret Manager API (Optional, for later posts, if using External Secrets Operator)

4. Workstation Setup

We’ll install the tools needed to interact with Google Cloud and Kubernetes from your local machine.

4.1 Install Google Cloud CLI (gcloud)

macOS (Homebrew):

brew install --cask google-cloud-sdk

Ubuntu / WSL2:

sudo apt-get update && sudo apt-get install -y apt-transport-https ca-certificates gnupg
echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] http://packages.cloud.google.com/apt cloud-sdk main" \
 | sudo tee /etc/apt/sources.list.d/google-cloud-sdk.list
curl -fsSL https://packages.cloud.google.com/apt/doc/apt-key.gpg \
 | sudo gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg
sudo apt-get update && sudo apt-get install -y google-cloud-cli

4.2 Authenticate with Google Cloud

Find your Project ID:

1. Go to the Google Cloud Console Projects Page
2. Look for your platform-starter-kit project.
3. Copy the Project ID from the ID column — it might match the name or have a small variation (e.g., platform-starter-kit or platform-starter-kit-123abc).

Log in with your Google account

💡 Note:

--no-launch-browser is only needed if you’re using WSL or a headless environment.

If you’re on macOS or Linux with a GUI, you can omit it.

With --no-launch-browser, gcloud will print a login URL instead of opening your browser automatically. Copy the URL into your Windows browser, complete login, then paste/confirm the code back in the terminal.

gcloud auth login --no-launch-browser

Also set application default credentials (used by Terraform later)

gcloud auth application-default login --no-launch-browser

Set the quota project for ADC (to avoid quota errors):

gcloud auth application-default set-quota-project <YOUR_PROJECT_ID>
# e.g.,
gcloud auth application-default set-quota-project platform-starter-kit

4.3 Set Your Defaults

Set your project:

gcloud config set project <YOUR_PROJECT_ID>
# e.g.,
gcloud config set project platform-starter-kit

Choose your preferred region and zone:

• Full list of available locations: GCP Regions and Zones
• Pick one closest to you or where you plan to deploy workloads.

Examples:

# US Central
gcloud config set compute/region us-central1
gcloud config set compute/zone us-central1-a

# Asia Northeast 3 (Seoul)
gcloud config set compute/region asia-northeast3
gcloud config set compute/zone asia-northeast3-a

# Canada
gcloud config set compute/region northamerica-northeast1
gcloud config set compute/zone northamerica-northeast1-a

4.4 Install Terraform

macOS:

brew tap hashicorp/tap
brew install hashicorp/tap/terraform

Ubuntu / WSL2:

sudo apt-get update && sudo apt-get install -y wget gpg
wget -O- https://apt.releases.hashicorp.com/gpg | gpg --dearmor \
 | sudo tee /usr/share/keyrings/hashicorp-archive-keyring.gpg >/dev/null
echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] \
https://apt.releases.hashicorp.com $(lsb_release -cs) main" \
 | sudo tee /etc/apt/sources.list.d/hashicorp.list
sudo apt-get update && sudo apt-get install -y terraform

Check:

terraform -version

4.5 Install kubectl

macOS:

brew install kubectl

Ubuntu / WSL2:

sudo apt-get update && sudo apt-get install -y kubectl

Check:

kubectl version --client

4.6 Install Helm

macOS:

brew install helm

Ubuntu / WSL2:

curl -fsSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

Check:

helm version

4.7 (Optional) Argo CD CLI

macOS:

brew install argocd

Ubuntu / WSL2:

VERSION=$(curl -s https://api.github.com/repos/argoproj/argo-cd/releases/latest \
 | grep tag_name | cut -d '"' -f 4)
curl -sSL -o argocd-linux-amd64 \
  "https://github.com/argoproj/argo-cd/releases/download/${VERSION}/argocd-linux-amd64"
sudo install -m 555 argocd-linux-amd64 /usr/local/bin/argocd
rm argocd-linux-amd64

Check:

argocd version --client

4.8 Docker (Optional Now, Required Later)

macOS / Windows: Install Docker Desktop. (WSL2 also requires Docker Desktop unless you install and run Docker Engine inside WSL with systemd enabled.)
Ubuntu / WSL2: Install Docker Engine and add your user to the docker group.

# 1. Remove old versions if they exist
sudo apt-get remove docker docker-engine docker.io containerd runc

# 2. Update and install dependencies
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg

# 3. Add Docker’s official GPG key
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# 4. Add the Docker repository
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 5. Install Docker Engine, CLI, and containerd
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 6. Add your user to the docker group
sudo usermod -aG docker $USER

# 7. Log out and log back in for the group change to take effect
exit

Verify installation:

docker --version
docker run hello-world

5. Minimal Project Config

5.1 Create .env.sample and per-env .env.*

.env.* is for later automation for Makefile/Terraform, CI.

mkdir -p terraform/gcp helm argocd templates platform-cli docs .github/workflows

cat > .env.sample <<'EOF'
# Platform Starter Kit - Environment template
# Copy this to: .env.<env>  (dev|staging|prod)
# Please update values with yours.
# ⚠️ Do NOT commit .env.* files; commit only .env.sample

PROJECT_ID=your-gcp-project-id

# Location
REGION=your-region            # e.g., northamerica-northeast1
ZONE=your-zone                # e.g., northamerica-northeast1-a

# GKE cluster name (short + env-specific)
CLUSTER_NAME=psk-<env>-gke    # e.g., psk-dev-gke

# Artifact Registry
REGISTRY_LOCATION=your-region
REGISTRY_REPO=apps-<env>      # e.g., apps-dev, apps-staging, apps
EOF

Then, create your local env files (edit values in these)

cp .env.sample .env.dev
cp .env.sample .env.staging
cp .env.sample .env.prod

Update the three files:

• .env.dev → CLUSTER_NAME=psk-dev-gke, REGISTRY_REPO=apps-dev
• .env.staging → CLUSTER_NAME=psk-stg-gke, REGISTRY_REPO=apps-staging
• .env.prod → CLUSTER_NAME=psk-prod-gke, REGISTRY_REPO=apps

.env.dev (example):

PROJECT_ID=platform-starter-kit
REGION=northamerica-northeast1
ZONE=northamerica-northeast1-a
CLUSTER_NAME=psk-dev-gke
REGISTRY_LOCATION=northamerica-northeast1
REGISTRY_REPO=apps-dev

.env.staging (example):

PROJECT_ID=platform-starter-kit
REGION=northamerica-northeast1
ZONE=northamerica-northeast1-b
CLUSTER_NAME=psk-stg-gke
REGISTRY_LOCATION=northamerica-northeast1
REGISTRY_REPO=apps-staging

.env.prod (example):

PROJECT_ID=platform-starter-kit
REGION=northamerica-northeast1
ZONE=northamerica-northeast1-c
CLUSTER_NAME=psk-prod-gke
REGISTRY_LOCATION=northamerica-northeast1
REGISTRY_REPO=apps

5.2 Quick Sanity Check

# Project exists
gcloud projects describe $(gcloud config get-value project) --format='value(projectId)'

# Required APIs enabled?
gcloud services list --enabled | grep -E 'container|compute|artifactregistry' || true

# CLIs present
terraform -version && kubectl version --client && helm version

If these work, your environment is ready for Post 2.

Adding it before your first commit

cat > .gitignore <<'EOF'
# Environment files
.env*
.env.*
!.env.sample

# Python cache
__pycache__/
*.pyc

# Node.js (if using React templates)
node_modules/

# Terraform
*.tfstate
*.tfstate.*
.terraform/
.terraform.lock.hcl

# Helm
chart/*.tgz

# OS / editor files
.DS_Store
Thumbs.db
.idea/
.vscode/

# Logs
*.log
EOF

Save Your Work for This Post

Before moving on, commit your changes and create a branch for this post so you can track progress separately for each step in the series.

git add .
git commit -m "Post 01: Introduction and Prerequisites setup"
git checkout -b post-01-intro-prerequisites
git push -u origin post-01-intro-prerequisites

This creates a branch named post-01-intro-prerequisites in your repository, containing everything you set up in this post.
In the next post, we’ll work from this baseline.

Next in the Series

In Post 2, we’ll:

• Add a Makefile for common commands
• Scaffold Terraform modules + per-env folders
• Bootstrap a minimal VPC + GKE cluster with Terraform