GCP Provider - Control Plane

The GCP provider lets you deploy worker nodes in your GCP project. As a prerequisite, only a network and a subnet need to exist.

Requirements

GCP Project

Supported add-ons

Dashboard: Provides a Kubernetes dashboard UI for the cluster.
Headlamp: The recommended dashboard for the cluster
AWS Workload Identity: Allows your pods to assume AWS IAM Roles.
AWS ECR: Allows pulling images from private ECR registries.
Local Path Storage: Create PVCs backed by local volumes.
Logs: Enable logging for pods and cluster auditing.
Metrics: Enable metrics collections.

Step 1 - Preparing the GCP project

Ensure your GCP project has:

A VPC with a subnet in the desired region

Service account withe these roles

Role	Description
`roles/compute.instanceAdmin.v1`	Instances, instance groups, templates
`roles/compute.loadBalancerAdmin`	Forwarding rules, target pools, addresses
`roles/compute.storageAdmin`	Disks and snapshots
`roles/compute.securityAdmin`	Firewall rules
`roles/compute.networkViewer`	Networks/subnets discovery (for validation)

Create a JSON key for the service account and store it in Control Plane as a secret of type GCP.

Permissions can further be restricted using expressions and limiting the scope of the role. Yet Control Plane must be able

Step 2 - Create a Managed Kubernetes Cluster Using a Manifest File

Update the manifest below: Modify the following gcp-mk8s-template.yaml YAML manifest below with actual values. Customize the file as needed.

Replace placeholders for ${PROJECT_ID}, ${NETWORK}, ${SUBNET}, ${SECRET} and ${ZONE}.

kind: mk8s
name: ${NAME}
spec:
  provider:
    gcp:
      projectId: ${PROJECT_ID}
      region: ${REGION}
      image:
        recommended: ubuntu/noble-24.04 # COS linux not yet supported
      saKeyLink: //secret/${SECRET} # points to the secret with the SA JSON key
      network: mk8s
      labels:                   # labels to attach to created GCP resources
        my-google-label: x123
      metadata:                 # metadata to attach to created instances
        my-google-meta1: hello world
      tags:                     # tags to attach to created instances
        - my-google-tag1
        - my-google-tag2
      nodePools:
        - name: general
          bootDiskSize: 30
          machineType: ${MACHINE_TYPE}
          localPersistentDisks: 1
          minSize: 1
          maxSize: 2
          subnet: ${SUBNET}
          zone: ${ZONE}
  addOns:
    headlamp: {}
  version: 1.32.9

This example creates a managed Kubernetes cluster in your project with the following configurations:

Kubernetes Version: 1.32.9.
Add-ons: Only the headlamp add-on is enabled
Node Pool: A single general node pool, scaling on-demand between 1 and 2 nodes.
Server Image: ubuntu/noble-24.04.

Create the Cluster: Deploy the gcp-mk8s-example cluster by applying the manifest.
- Console: Apply the gcp-mk8s-template.yaml file using the cpln apply >_ option in the upper right corner.
- CLI: Execute cpln apply -f gcp-mk8s-template.yaml --org YOUR_ORG_HERE.
Wait until the cluster is initialized.

Step 3 - Accessing the Cluster

1. Using the Terminal

Obtain the Cluster’s Kubeconfig File: Execute the command cpln mk8s kubeconfig gcp-mk8s-example -f /tmp/gcp-mk8s-example-conf.
Access the Cluster with kubectl: Use the obtained kubeconfig file by running export KUBECONFIG=/tmp/gcp-mk8s-example-conf for the current shell session.

2. Using Kubernetes Dashboard

Navigate to Control Plane Console: Visit the Control Plane Console.
Access the Dashboard: In the Control Plane Console, navigate to Kubernetes in the left sidebar panel and click on Open under Headlamp for the cluster gcp-mk8s-example.

Advanced Configuration Options

Instance rotation/refresh

Sometimes an explicit rotation (or refresh) of the instances in the Auto-Scaling Group is needed. For example to get the latest image or new boot disk size. To do this per node pool, add a label cpln.io/refreshToken with an arbitrary valid value. Every time the value of this label changes Control Plane will start a conservative instance replacement (1 instance at a time). If you remove that label it’s the same as having an empty value and that will trigger refresh too.

​Requirements

​Supported add-ons

​Step 1 - Preparing the GCP project

​Step 2 - Create a Managed Kubernetes Cluster Using a Manifest File

​Step 3 - Accessing the Cluster

​1. Using the Terminal

​2. Using Kubernetes Dashboard

​Advanced Configuration Options

​Instance rotation/refresh

Requirements

Supported add-ons

Step 1 - Preparing the GCP project

Step 2 - Create a Managed Kubernetes Cluster Using a Manifest File

Step 3 - Accessing the Cluster

1. Using the Terminal

2. Using Kubernetes Dashboard

Advanced Configuration Options

Instance rotation/refresh