Google GKE Cluster

Google GKE Cluster Provisioner

The Google GKE Cluster Provisioner deploys a production-ready Kubernetes cluster on Google Cloud Platform (GCP), using dynamic credentials — no service account keys needed.

GKE Specification

The gke struct configures the GKE provisioner.

projectId: Required GCP project ID.
networkId: Optional field for VPC network (required for BYOVPC).
subnet: Optional subnet configuration for BYOVPC (required when networkId is provided).
- subnet.name: Name of the regional subnet.
- subnet.podsRange: Name of the secondary IP range for pods.
- subnet.servicesRange: Name of the secondary IP range for services.
autopilot: Optional field to enable Autopilot mode (default: false).
releaseChannel: Optional field for release channel (RAPID, REGULAR, STABLE).
kubernetesVersion: Optional field for Kubernetes version.
enableWorkloadIdentity: Optional field to enable Workload Identity (default: true).
masterIPv4CidrBlock: Optional field for control plane CIDR (must be /28, RFC 1918).
authorizedNetworks: Optional field for authorized networks (max 50 CIDRs).
labels: Optional field for resource labels.
credentials: Required field for cloud provider credentials.

Bring your own VPC (BYOVPC)

For BYOVPC, provide networkId and subnet configuration. GKE uses regional subnets (not per-zone like EKS), so you only need one subnet that spans all zones in your region. Secondary IP ranges for pods and services must be pre-configured on your subnet.

Prerequisites

Required tools

Google Cloud CLI — required for kubeconfig token generation and Cloud Shell
kubectl (optional) — for direct cluster interaction
astroctl — for cluster management

Finding your GCP credentials

You need your GCP project ID. Run:

gcloud config get-value project

Example output: my-project-123456

Enable the GKE API on the project if it is not already enabled:

gcloud services enable container.googleapis.com --project <YOUR_GCP_PROJECT_ID>

Find available regions and zones

astroctl cloud gcp regions list
astroctl cloud gcp regions zones list -r <region-name>

Connect your GCP project

Run this once per cluster before creating it. Omitting this step will cause an error during cluster creation.

astroctl cloud gcp connect \
  --project-id <YOUR_GCP_PROJECT_ID> \
  --cluster-name <YOUR_CLUSTER_NAME> \
  --region <YOUR_REGION>

Example:

astroctl cloud gcp connect \
  --project-id my-project-123456 \
  --cluster-name my-gke-cluster \
  --region us-central1

The CLI generates a setup script and opens Google Cloud Shell in your browser. Cloud Shell uses your browser's active Google account — make sure it has access to the target project. In Cloud Shell, run the one-liner shown in the terminal. The CLI waits and confirms when the project is connected.

Run locally instead of Cloud Shell

If you have gcloud installed and authenticated locally, add --local to save the setup script and run it in your own terminal:

astroctl cloud gcp connect --project-id my-project-123456 --cluster-name my-gke-cluster --region us-central1 --local

Use the same --cluster-name and --region values when you create the cluster.

Fleet Hub enrollment is automatic

AstroPulse registers the cluster in GCP Fleet Hub during creation to enable Connect Gateway. You do not need to run gcloud container fleet memberships register manually.

Complete Field Reference

The gke struct configures the GKE provisioner. This is the authoritative reference for all available fields.

Core Fields

Field	Type	Required	Default	Description
`projectId`	string	Yes	-	GCP project ID where the cluster will be created
`credentials`	object	Yes	-	Cloud provider credentials. Use `type: dynamic` (set up via `astroctl cloud gcp connect`)

Networking Fields

Field	Type	Required	Default	Description
`networkId`	string	No	-	Existing VPC network name for BYOVPC. If not provided, platform creates a new production-ready VPC
`networkCIDR`	string	No	`10.0.0.0/16`	CIDR for new VPC. Must be RFC 1918, prefix /8 to /29. See Supported CIDR Ranges
`subnet`	object	No*	-	Regional subnet configuration for BYOVPC. *Required when `networkId` is provided
`subnet.name`	string	Yes**	-	Name of the regional subnet
`subnet.podsRange`	string	Yes**	-	Name of the secondary IP range for pods
`subnet.servicesRange`	string	Yes**	-	Name of the secondary IP range for services
`masterIPv4CidrBlock`	string	No	`172.16.0.0/28`	CIDR for GKE control plane. Must be exactly `/28` in RFC 1918 range
`authorizedNetworks`	[]string	No	-	CIDR blocks allowed to access the Kubernetes API. Max 50 entries. If not set, API is unrestricted

*Required when networkId is provided. **Required fields within subnet object.

Cluster Configuration Fields

Field	Type	Required	Default	Description
`autopilot`	boolean	No	`false`	Enable GKE Autopilot mode. When enabled, Google manages all node operations
`releaseChannel`	string	No	`STABLE`	Release channel for automatic upgrades. Values: `RAPID`, `REGULAR`, `STABLE`
`kubernetesVersion`	string	No	Channel default	Kubernetes version. Accepts: `1.30.14`, `1.30.14-gke.1096000`, or empty for channel default
`enableWorkloadIdentity`	boolean	No	`true`	Enable Workload Identity for secure pod-to-GCP service authentication
`labels`	map[string]string	No	-	Key-value pairs for GCP resource labeling

Field Validation Rules

Field	Validation
`projectId`	Must be a valid GCP project ID (lowercase, hyphens allowed)
`networkId`	Must be 1-63 lowercase letters, digits, or hyphens. Start with letter, end with letter or digit
`networkCIDR`	Must be valid CIDR notation (e.g., `10.0.0.0/16`)
`subnet.name`	Must be 1-63 lowercase letters, digits, or hyphens. Start with letter, end with letter or digit
`masterIPv4CidrBlock`	Must be exactly `/28` prefix in RFC 1918 range (10.x, 172.16-31.x, 192.168.x)
`authorizedNetworks`	Each entry must be valid CIDR. Maximum 50 entries allowed
`releaseChannel`	Must be one of: `RAPID`, `REGULAR`, `STABLE`
`kubernetesVersion`	Must be valid K8s version format: `1.30` or `1.30.14` or `1.30.14-gke.1096000`

Bring Your Own Account (BYOA)

The astro platform allows you to bring your own GCP project for GKE cluster creation. The following example illustrates the GKE specification, with the platform managing VPC, subnet, and other networking configurations. You only need to provide the project ID and ensure proper quotas and API enablement. The astroctl will verify these before cluster creation.

apiVersion: platform.astropulse.io/v1
kind: K8sCluster
spec:
  clusterName: my-gke-cluster
  provider: gcp
  region: us-central1
  provisioner:
    type: gke
    gke:
      projectId: "my-project-123"
      labels:
        environment: "dev"
        owner: "platform-team"
      credentials:
        type: dynamic  # dynamic credentials — set up via astroctl cloud gcp connect
  clusterSpec:
    dataPlane:
      nodeGroups:
        - name: default-pool
          minNode: 1
          maxNode: 3
          instanceType: ondemand  # or "spot" for cost savings
          machineTypes:
            - e2-medium
          labels:
            environment: production

Autopilot Mode

GKE Autopilot is a fully managed Kubernetes mode where Google handles node provisioning, scaling, and security updates. This is recommended for teams that want zero node management overhead.

apiVersion: platform.astropulse.io/v1
kind: K8sCluster
spec:
  clusterName: my-autopilot-cluster
  provider: gcp
  region: us-central1
  provisioner:
    type: gke
    gke:
      projectId: "my-project-123"
      autopilot: true  # Enable Autopilot mode
      credentials:
        type: dynamic
  # Note: clusterSpec with nodeGroups is optional for Autopilot - GKE manages nodes automatically

Autopilot Benefits

Zero node management: Google handles all node operations
Per-pod billing: Pay only for pod resources, not nodes
Automatic security: Security updates applied automatically
Built-in best practices: Google's recommended configurations applied by default

Bring Your Own VPC (BYOVPC)

When using an existing VPC, you must configure a regional subnet with secondary IP ranges for pods and services. GKE uses VPC-native networking which requires these secondary ranges.

GKE Networking Architecture

GKE uses regional subnets (not per-zone like AWS EKS). A single subnet spans all zones in a region, and GKE automatically distributes nodes across zones.

See Networking Overview for visual diagrams for GKE architectures.

BYOVPC Prerequisites

Before using BYOVPC, you must create:

VPC Network (custom mode recommended)
Regional Subnet with secondary IP ranges for pods and services
Enable Private Google Access on the subnet (recommended)

Step-by-Step Setup

Step 1: Create VPC Network (if needed)

gcloud compute networks create my-vpc \
  --subnet-mode=custom \
  --project=my-project-123

Step 2: Create Subnet with Secondary Ranges

gcloud compute networks subnets create gke-subnet \
  --network=my-vpc \
  --region=us-central1 \
  --range=10.0.0.0/20 \
  --secondary-range=pods=10.4.0.0/14 \
  --secondary-range=services=10.0.16.0/20 \
  --enable-private-ip-google-access \
  --project=my-project-123

Step 3: Create Firewall Rules (optional)

gcloud compute firewall-rules create allow-internal \
  --network=my-vpc \
  --allow=tcp,udp,icmp \
  --source-ranges=10.0.0.0/8 \
  --project=my-project-123

BYOVPC Configuration

The subnet field specifies your regional subnet and the names of the secondary IP ranges:

Field	Description	Required
`subnet.name`	Name of the regional subnet	Yes
`subnet.podsRange`	Name of the secondary IP range for pods	Yes
`subnet.servicesRange`	Name of the secondary IP range for services	Yes

BYOVPC Example

apiVersion: platform.astropulse.io/v1
kind: K8sCluster
spec:
  clusterName: gke-byovpc-cluster
  provider: gcp
  region: us-central1
  provisioner:
    type: gke
    gke:
      projectId: "my-project-123"
      networkId: "my-vpc"
      subnet:
        name: "gke-subnet"           # Regional subnet name
        podsRange: "pods"            # Secondary range name for pods
        servicesRange: "services"    # Secondary range name for services
      masterIPv4CidrBlock: "172.16.0.0/28"
      authorizedNetworks:
        - "10.0.0.0/8"
        - "192.168.1.0/24"
      labels:
        environment: "production"
      credentials:
        type: dynamic
  clusterSpec:
    dataPlane:
      nodeGroups:
      - name: app-pool
        minNode: 2
        maxNode: 5
        instanceType: ondemand
        machineTypes:
        - e2-standard-4
        labels:
          tier: application
      - name: system-pool
        minNode: 1
        maxNode: 3
        instanceType: ondemand
        machineTypes:
        - e2-medium
        labels:
          tier: system
        taints:
        - key: dedicated
          value: system
          effect: NoSchedule

Validation

The CLI validates your BYOVPC configuration before cluster creation:

Checks VPC network exists
Verifies subnet exists in the specified region
Confirms secondary IP ranges exist with the specified names
Warns if Private Google Access is not enabled

Supported CIDR Ranges

GKE requires all network CIDRs to be within RFC 1918 private address space:

RFC 1918 Range	CIDR Block	Available IPs	Common Use
Class A	`10.0.0.0/8`	16,777,216	Large enterprise networks
Class B	`172.16.0.0/12`	1,048,576	Medium networks (172.16.x.x - 172.31.x.x)
Class C	`192.168.0.0/16`	65,536	Small networks

VPC/Network CIDR (networkCIDR):

Prefix length: /8 to /29
Must not overlap with other VPCs or peered networks
Default: 10.0.0.0/16

Examples:

networkCIDR: "10.0.0.0/16"      # 65,536 IPs (recommended)
networkCIDR: "172.16.0.0/16"    # 65,536 IPs
networkCIDR: "192.168.0.0/16"   # 65,536 IPs
networkCIDR: "10.100.0.0/20"    # 4,096 IPs (smaller network)

Recommended IP Ranges

For GKE clusters, we recommend the following CIDR allocations:

Range Type	Recommended CIDR	Prefix	IP Count	Notes
Nodes (primary subnet)	`10.0.0.0/20`	/20	4,096	Subnet primary range
Pods (secondary range)	`10.4.0.0/14`	/14	262,144	Supports ~1,000 nodes with 110 pods each
Services (secondary range)	`10.0.16.0/20`	/20	4,096	Sufficient for most clusters
Control plane	`172.16.0.0/28`	/28	16	GKE master nodes (required /28)

Control Plane Network Configuration

Master IPv4 CIDR Block

The masterIPv4CidrBlock specifies the IP range for the GKE control plane (master nodes).

Requirement	Value
Prefix Length	Must be exactly `/28` (16 IP addresses)
IP Range	Must be in RFC 1918 private range
Default	`172.16.0.0/28`

Valid RFC 1918 ranges:

10.0.0.0/8 - Class A private
172.16.0.0/12 - Class B private (172.16.x.x - 172.31.x.x)
192.168.0.0/16 - Class C private

Example values:

masterIPv4CidrBlock: "172.16.0.0/28"   # Default (recommended)
masterIPv4CidrBlock: "172.16.0.16/28"  # If default conflicts
masterIPv4CidrBlock: "10.0.0.0/28"     # Using 10.x range
masterIPv4CidrBlock: "192.168.0.0/28"  # Using 192.168.x range

When to Change

Only change the default if 172.16.0.0/28 conflicts with your existing network infrastructure. The control plane CIDR must not overlap with your VPC subnets, pod ranges, or service ranges.

Authorized Networks

The authorizedNetworks field specifies which CIDR blocks are allowed to access the Kubernetes API server.

Requirement	Value
Format	Valid CIDR notation (e.g., `10.0.0.0/8`)
Maximum Entries	50
Default	None (unrestricted access - not recommended for production)

Example configurations:

# Recommended: Restrict to internal networks
authorizedNetworks:
  - "10.0.0.0/8"         # All RFC 1918 Class A (internal VPC)
  - "172.16.0.0/12"      # All RFC 1918 Class B
  - "192.168.0.0/16"     # All RFC 1918 Class C

# Restrictive: Only specific networks
authorizedNetworks:
  - "10.128.0.0/16"      # Your VPC subnet
  - "192.168.1.0/24"     # Office network
  - "203.0.113.5/32"     # Single admin IP

# VPN-only access
authorizedNetworks:
  - "10.10.0.0/16"       # VPN client range

Security Recommendation

For production clusters, always specify authorizedNetworks to restrict API access. Leaving it empty allows anyone on the internet to attempt to access your Kubernetes API.

Cluster Updates

GKE clusters support updates to Kubernetes version, node pool configurations, and cluster settings. You can use either the Console UI or the CLI.

Option 1: Console (Upgrade Wizard)

The Console provides a guided 5-step upgrade wizard:

Preflight Check - Validates upgrade paths and checks for issues
Readiness Report - Generates comprehensive upgrade analysis with risk score
Pre-Upgrade Checklist - Interactive checklist with verification commands
Configuration - Select target version and rolling update settings
Confirmation - Review summary and confirm by typing cluster name

To access: Go to Clusters → Select cluster → Click Upgrade button

The wizard shows:

Visual version timeline (current → next → locked future versions)
Node pool scaling controls (min/max nodes)
Rolling update settings (maxSurge, maxUnavailable)
Impact summary before execution

Option 2: CLI Commands

Version Discovery

# List available versions for this cluster
astroctl infra k8s upgrade <cluster-name> --list-versions

# Check versions for a region
astroctl cloud gcp k8s-versions
astroctl cloud gcp k8s-versions -r us-central1
astroctl cloud gcp k8s-versions --show-upgrade-paths

Kubernetes Version Upgrade

# Dry-run validation first
astroctl infra k8s upgrade <cluster-name> 1.30 --dry-run

# Generate readiness report
astroctl infra k8s upgrade <cluster-name> 1.30 --generate-report

# Execute upgrade
astroctl infra k8s upgrade <cluster-name> 1.30

# Skip confirmation (for automation)
astroctl infra k8s upgrade <cluster-name> 1.30 --yes

Rollback Node Pools

GKE control plane cannot be rolled back. Node pools will be downgraded to the target version (max 2 minor versions behind control plane).

# List versions available for rollback
astroctl infra k8s rollback <cluster-name> --list-versions

# Dry-run first — validates rollback path and warns about limitations
astroctl infra k8s rollback <cluster-name> 1.29 --dry-run

# Execute rollback
astroctl infra k8s rollback <cluster-name> 1.29 --yes

Scaling Node Pools

# List node pools
astroctl infra k8s scale <cluster-name> --list

# Preview changes first (dry-run)
astroctl infra k8s scale <cluster-name> <nodepool-name> --min 3 --max 10 --dry-run

# Apply the scale
astroctl infra k8s scale <cluster-name> <nodepool-name> --min 3 --max 10

Advanced Updates (YAML)

# Show YAML examples for your cluster
astroctl infra k8s update <cluster-name> --example

# Dry-run validation first
astroctl infra k8s update <cluster-name> -f update.yaml --dry-run

# Apply update
astroctl infra k8s update <cluster-name> -f update.yaml

# Skip confirmation (for automation)
astroctl infra k8s update <cluster-name> -f update.yaml --auto-approve

Monitor Progress

# Stream real-time progress
astroctl infra k8s progress stream <cluster-name>

# Get current status
astroctl infra k8s progress get <cluster-name>

# View operation history
astroctl infra k8s progress history <cluster-name>

Update File Reference

apiVersion: platform.astropulse.io/v1
kind: K8sClusterUpdate
spec:
  # Kubernetes version
  kubernetesVersion: "1.30"

  # Rolling update configuration
  updateConfig:
    maxSurge: "1"           # Nodes added during update (number or %)
    maxUnavailable: "1"     # Nodes down during update (number or %)
    dryRun: false           # Validate without applying
    generateReport: false   # Generate readiness report

  # Node pools
  nodeGroups:
    - name: "default-pool"
      minNode: 2
      maxNode: 8
      machineTypes: ["n2-standard-4"]
      instanceType: "ondemand"  # or "spot"
      labels:
        workload: "general"

  # GKE-specific settings
  gke:
    imageType: "UBUNTU_CONTAINERD"
    releaseChannel: "REGULAR"
    maintenanceWindow:
      startTime: "2024-01-20T03:00:00Z"
      duration: "4h"
    authorizedNetworks:
      - "10.0.0.0/8"

  # Resource labels
  tags:
    environment: "production"

GKE Update Options

Field	Values	Description
`gke.imageType`	`COS_CONTAINERD`, `COS`, `UBUNTU_CONTAINERD`, `UBUNTU`	Node image type (changing triggers node replacement)
`gke.releaseChannel`	`RAPID`, `REGULAR`, `STABLE`	Release channel for version management
`gke.maintenanceWindow.startTime`	RFC3339 format	Maintenance window start (e.g., `2024-01-20T03:00:00Z`)
`gke.maintenanceWindow.duration`	Duration string	Window duration (min: `4h`, max: `48h`)
`gke.authorizedNetworks`	CIDR array	Networks allowed to access API server

Rolling Update Strategy

Control the speed and safety of node pool upgrades with --max-unavailable and --max-surge flags:

# Configure rolling update speed
astroctl infra k8s upgrade my-cluster 1.30 --max-unavailable 2 --max-surge 1

# Use percentage-based configuration
astroctl infra k8s upgrade my-cluster 1.30 --max-unavailable 25%

Smart Defaults: If you don't specify these flags, AstroPulse automatically determines optimal values per node pool:

Node Pool Type	Default Strategy	Why
Small (1-3 nodes)	surge=1, unavailable=0	Maintain full capacity
Medium (4-10 nodes)	surge=2, unavailable=1	Balance speed and safety
Large (10+ nodes)	surge=10%, unavailable=10%	Percentage-based scaling
GPU nodes	surge=1, unavailable=0	Protect expensive resources
System/Critical	surge=1, unavailable=0	Ensure cluster stability

Per-Node-Pool Optimization

GKE supports per-node-pool rolling update settings. AstroPulse analyzes each pool's characteristics (size, labels, machine types) to apply optimal settings automatically.

Upgrade Process

Control plane is upgraded first
Node pools are upgraded sequentially with per-pool rolling update settings
Progress is tracked and reported in real-time

Upgrade Considerations

GKE only supports sequential minor version upgrades (cannot skip versions, e.g., 1.29 → 1.30 → 1.31)
Control plane cannot be downgraded after upgrade
Always test upgrades in a non-production environment first

KubeConfig

With a simple command like below, you can set the context to the cluster and have access to the cluster. You need to make sure to install the kubectl CLI as required.

astroctl infra k8s set-context <cluster-name>

The kubeconfig uses the gcloud CLI for dynamic token generation — no static credentials stored.

Added Capabilities

The GKE provisioner automatically enables the following capabilities for GKE clusters:

Node Auto-Provisioning (NAP): Automatic node type selection and scaling based on workload requirements. GKE selects optimal machine types for your pods.
- Resource limits: CPU (10-1000 cores), Memory (40-4000GB)
- BALANCED profile for even distribution across zones
Workload Identity: Pod-level IAM for secure access to GCP services without service account keys.
Shielded Nodes: Secure Boot, vTPM, and Integrity Monitoring enabled by default.
Network Policies: Calico-based network policies for micro-segmentation.
Dataplane V2: Optional eBPF-based networking for better performance and observability.
VPC-Native Networking: Alias IP ranges for pod and service IPs.
Private Clusters: Optional. Set privateCluster: true to give nodes private IPs only. The platform's deployment service works with private clusters without any additional configuration.

Release Channels

GKE offers three release channels for automatic version management:

RAPID: Weekly updates, best for testing and development
REGULAR: Bi-weekly updates, balanced approach
STABLE: Monthly updates, recommended for production (default)

Security

What you get out of the box

What	How
No stored credentials	The platform mints short-lived GCP tokens on demand. No long-lived service account keys are stored anywhere in AstroPulse infrastructure.
No direct internet exposure required	The platform's deployment service connects to your cluster through a Google-managed relay. Your cluster API server does not need to be reachable from the internet for the platform to deploy applications.
Workload Identity	Enabled by default. Your pods can authenticate to GCP services (Secret Manager, GCS, etc.) using IAM roles without embedding keys in containers.
Shielded Nodes	Secure Boot, vTPM, and Integrity Monitoring are enabled on all nodes.
Network Policies	Calico-based network policies for pod-level micro-segmentation.

How to harden further

Private cluster (recommended for production)

Set privateCluster: true in your cluster spec. Nodes get private IPs only. The platform's deployment service continues to work without any change — it does not require direct access to your cluster API server.

provisioner:
  type: gke
  gke:
    privateCluster: true
    masterIPv4CidrBlock: "172.16.0.16/28"  # required when privateCluster is true

Restrict kubectl access with authorized networks

authorizedNetworks controls which CIDRs can reach your cluster API server directly (for kubectl, helm, etc.). This does not affect platform deployments.

provisioner:
  type: gke
  gke:
    authorizedNetworks:
      - "203.0.113.0/24"   # your office / VPN egress IP
      - "10.0.0.0/8"       # internal network

Workload Identity for your applications

Enable enableWorkloadIdentity: true (default) and annotate your Kubernetes service accounts with the GCP service account email to grant pods fine-grained GCP API access without credentials in code.

Private cluster + Connect Gateway

Setting privateCluster: true is the strongest network posture for a platform-managed GKE cluster. The platform's deployment service reaches private clusters without requiring any firewall rules, VPN, or public endpoint.