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

To create a GKE cluster on GCP, ensure the following CLI tools are installed on your local machine:

Google Cloud CLI for GKE cluster communication
kubectl (optional) for GKE cluster interaction
astroctl for cluster management

Connect your GCP account before creating a cluster — this is required and only needs to be done once per cluster:

astroctl cloud gcp connect --project-id <project-id> --cluster-name <cluster-name> --region <region>

The CLI opens Google Cloud Shell in your browser with a setup script ready to run. Follow the instructions shown in the terminal.

Example

astroctl cloud gcp connect --project-id my-project-123 --cluster-name my-cluster --region us-central1

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

Region and Zone Identification

Identify the region and zones using the GCP console or the following commands:

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

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

Scaling Node Pools

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

# Scale a node pool
astroctl infra k8s scale <cluster-name> <nodepool-name> --min 3 --max 10

# Preview changes
astroctl infra k8s scale <cluster-name> <nodepool-name> --min 5 --max 20 --dry-run

Advanced Updates (YAML)

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

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

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

# Skip confirmation
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 private control plane and nodes (enabled by default).

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 Features

GKE clusters provisioned by Astro include the following security features by default:

Feature	Status	Description
Private Cluster	Enabled	No public IPs on nodes
Workload Identity	Enabled	Pod-level IAM without keys
Shielded Nodes	Enabled	Rootkit protection
Network Policies	Enabled	Calico micro-segmentation
Binary Authorization	Optional	Container image verification

Additional Security

You can enable additional security features like Binary Authorization, Container Analysis, and Policy Controller through the GCP console or gcloud CLI.