LocalCloud GKE Local Emulator
Get started
local.cloud / agents
Read this page as Markdown ↗
local.cloud — GKE Local Emulator .md Open tab

GKE

Google Kubernetes Engine manages Kubernetes clusters for container workloads. LocalCloud uses k3d to provide a local Kubernetes runtime alongside supported cluster metadata.

When to use GKE

Typical uses

Use when deployment depends on Kubernetes manifests and APIs, and you need cluster provisioning plus pod readiness checks. Local tests require Docker and k3d.

Examples

  • Kubernetes deployment tests
  • Cluster provisioning and readiness checks

GKE is opt-in to save memory. Add gke to the services you start, for example localcloud start --local-only --services gke,gcs,pubsub; --services sets the exact list.

Explore another service

View all

Example usage

Service ID: gke. Enable this service in the exact list of services your project starts; see the opt-in instruction above. Use an already running LocalCloud runtime for the examples below.

Export the local project and mapped endpoints in your client process, then use the client settings below. First-time setup

# Export GOOGLE_CLOUD_PROJECT and GKE_EMULATOR_HOST
eval "$(localcloud env)"

REST gateway examples use the generated HTTP address in SERVICE_USAGE_EMULATOR_HOST; native SDKs can use a different protocol.

Java · REST

List Kubernetes clusters

List Kubernetes clusters; GKE provides the cluster context where you deploy and inspect container workloads.

Call the Google Cloud REST API with the JDK HTTP client. Requires JDK 17+. Results reflect resources already created in your local project.

Discovery check · reads existing local state.

Save as Hello.java

import java.net.URI;
import java.net.http.*;
import java.time.Duration;
import java.util.Objects;

public class Hello {
  public static void main(String[] args) throws Exception {
    var project = Objects.requireNonNull(System.getenv("GOOGLE_CLOUD_PROJECT"));
    var endpoint = Objects.requireNonNull(System.getenv("SERVICE_USAGE_EMULATOR_HOST"));
    var url = URI.create(endpoint.replaceAll("/+$", "") + "/v1/projects/" + project + "/locations/us-central1/clusters");
    var request = HttpRequest.newBuilder(url).timeout(Duration.ofSeconds(30)).GET().build();
    var client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(10)).build();
    var response = client.send(request, HttpResponse.BodyHandlers.ofString());
    if (response.statusCode() >= 400) {
      throw new IllegalStateException(response.statusCode() + ": " + response.body());
    }
    System.out.println(response.body());
  }
}

Run the example

java Hello.java

Verify the result

The request succeeds. An empty list or no printed rows is valid before matching resources exist. Continue with the documented workflows for a resource test.

Verify a resource workflow by creating isolated state, performing the operation, and reading the result back. Run cleanup even after a failure; delete only test-owned resources.

Connection failed? Check localcloud status --verbose, enabled services, and client exports. Stop accidental Google Cloud calls; correct local routing before retrying.

Documented workflows

  • Cluster metadata lifecycle

    Create a cluster and poll its pending operation until k3d provisioning finishes. Inspect the terminal result before treating the cluster as available.

  • Real local Kubernetes clusters through k3d

    Use Docker and k3d to bring up the local Kubernetes cluster, then deploy a small workload. Check pod status and application output through Kubernetes.

  • Pod ADC through annotated Kubernetes-to-Google service-account bindings

    Enable TLS and local identity, configure the project workload pool, annotate the Kubernetes service account, and grant workloadIdentityUser to its Google service-account mapping. Check ADC inside a pod before calling a local API.

Service boundaries

  • One k3d server node; requires Docker. No node-pool creation, autoscaling, resize, or upgrades
  • Use the exported /container/v1 REST endpoint; shared /v1 cluster routes select AlloyDB
  • Pod identity needs TLS, local identity, the KSA annotation, and workloadIdentityUser; direct principal federation is unavailable
Agent testing

Use GKE with an AI agent

Before the agent changes application logic, have it create local GKE state, read it back with the project SDK, and note which feature the check covered. That first local call catches accidental production routing and needs no GCP account, service-account key, or billing project.

Configure this repo

Set up this repository to use LocalCloud for local GCP development. First read https://local.cloud/ai/agents.md, then inspect this repo, identify the GCP services and SDK language, configure emulator environment variables, and run the narrowest integration test against localhost. Do not use real GCP credentials or production endpoints.

Production endpoints, auth, IAM, quotas, regional behavior, and final release validation still need the target Google Cloud project.

Agent resources has more prompts and the AGENTS.md template.

Related guides

Desktop view