Skip to Content
GuideGKEGKE Getting Started

GKE Getting Started

This guide explains the basic CloudPilot AI flow for Google Kubernetes Engine (GKE): prepare access to the cluster, register it with CloudPilot AI, and install the Phase 2 optimization components.

Prerequisites

Before you begin, make sure you have:

  • a running GKE cluster that you can administer with kubectl
  • access to the CloudPilot AI console 
  • kubectl, gcloud, helm, jq, and curl installed in the environment where you will run the scripts
  • a GKE cluster with Workload Identity enabled before you start the Phase 2 install flow

The GKE Phase 1 path relies on cluster metadata to discover the cluster name and related context. You do not need to manually export CLUSTER_NAME in the Add Cluster script.

Step 1: Prepare cluster access

Export the basic identifiers for your cluster and make sure the current context points at the correct GKE cluster:

export GCP_PROJECT_ID=<your-project-id>
export CLUSTER_NAME=<your-cluster-name>
export CLUSTER_LOCATION=<your-cluster-location> # e.g. us-central1-a or us-central1
 
gcloud auth login
gcloud config set project "${GCP_PROJECT_ID}"
gcloud container clusters get-credentials "${CLUSTER_NAME}" \
  --location "${CLUSTER_LOCATION}" \
  --project "${GCP_PROJECT_ID}"
 
kubectl get nodes
helm version
jq --version

Choosing CLUSTER_LOCATION correctly

  • Zonal cluster: use a zone such as us-central1-a
  • Regional cluster: use a region such as us-central1

If the same cluster name exists in multiple locations, always export CLUSTER_LOCATION explicitly before running CloudPilot lifecycle scripts.

Step 2: Add the GKE cluster to CloudPilot AI (Phase 1)

  1. Sign in to the CloudPilot AI console .
  2. Click Add Cluster.
  3. Choose GKE.
  4. Copy the generated shell script and run it in your terminal or Cloud Shell.
  5. Return to the console and click I ran the script.

The generated GKE Add Cluster script installs the standard Phase 1 agent manifest and sets CLOUD_PROVIDER=gcp. At this stage, CloudPilot AI registers the cluster and assigns a CloudPilot CLUSTER_ID for later lifecycle operations.

Step 3: Install the optimization components (Phase 2)

After the cluster is registered, open the cluster page and click Start Saving. The GKE-specific Phase 2 script generated by the console exports the variables below before calling the GKE install entrypoint:

VariablePurpose
CLOUDPILOT_API_KEYAuthenticates the cluster to CloudPilot AI
GCP_PROJECT_IDSelects the Google Cloud project for GKE and Compute Engine operations
CLUSTER_IDSelects the CloudPilot AI cluster record
CLUSTER_NAMESelects the target GKE cluster
CLUSTER_REGIONKeeps the provider region context consistent for pricing and discovery
CLUSTER_LOCATIONPreserves the exact zonal or regional cluster location

The Phase 2 install script then performs the following checks and actions:

  • validates kubectl, helm, jq, curl, and gcloud
  • confirms the current Kubernetes context points to the target cluster
  • verifies GKE Workload Identity is enabled
  • creates or reuses the CloudPilot controller GSA
  • binds cloudpilot/cloudpilot-admin to that GSA through iam.gke.io/gcp-service-account
  • reconciles the least-privilege custom IAM role for the controller
  • installs the CloudPilot base components and the GCP optimizer Helm release

Step 4: Verify the installation

Once the script finishes, verify that the CloudPilot namespace is healthy:

kubectl -n cloudpilot get deploy
kubectl -n cloudpilot get pods

A healthy GKE installation normally includes deployments such as:

  • cloudpilot-agent
  • cloudpilot-controller
  • cloudpilot-webhook
  • cloudpilot-gcp-optimizer
  • cloudpilot-workload-log-collector

You can then return to the console to begin configuring NodePools, running rebalances, and enabling additional features such as the Workload Autoscaler.

Next steps

Last updated on
GKE Support OverviewGKE Day-2 Operations