Directory Layout

gck stores all persistent data under a single home directory. By default this is ~/.gck; override it by setting the GCK_HOME environment variable.

$GCK_HOME/
├── gck.yaml
├── clusters/
│   └── <cluster-name>.yaml
├── dns/
│   └── <cluster-name>.yaml
├── logs/
│   ├── build/
│   │   └── build.log
│   ├── delete.log
│   └── <context-path>/
│       ├── install.log
│       └── patch.log
├── mirrors/
│   ├── data/
│   └── hosts/
├── preload/
├── preload.lock
└── pids/
    ├── cpk.pid
    └── dns.pid

gck.yaml#

The user-level base config. Settings here are merged under every project config – use it for things like a custom registry URL, image mirrors, or a default DNS domain. This file is optional; see Config resolution order .

clusters/#

State files created automatically at the end of a successful gck create. Each file captures what gck delete needs for a clean teardown – the cluster name, enabled features and image configuration – and what gck patch reuses: the create-time from, --registry, --set overrides, context flags and the member of each alternative group.

clusters/
├── my-cluster.yaml
└── dev-stack.yaml

gck delete uses these files for target resolution . State files are removed after a successful delete.

Target resolution#

gck delete doesn’t need the original gck.yaml or registry to be available. It resolves the target cluster in this order:

  1. --name flag – If provided, gck looks up the state file for that cluster directly. Works from any directory.
  2. State files – If --name is omitted, gck scans clusters/ for existing state files. With one cluster, it’s deleted automatically. With multiple clusters, you get an interactive prompt.
  3. Config fallback – If no state files exist, gck reads kind.name from the config chain.

If you pass --name but no state file exists, gck performs a best-effort cleanup (Kind cluster, load balancer containers, DNS records) and prints a warning. The preload registry and mirror proxies are stopped as usual once no other gck cluster is running.

dns/#

DNS record files, one per cluster. Each file contains the hostname-to-IP mappings collected by gck create or gck refresh dns. The local DNS server watches this directory and hot-reloads when records change.

When a cluster is deleted, only its record file is removed – records from other clusters remain resolvable.

logs/#

Log files from cluster operations. Helm and kubectl output that isn’t shown in the terminal is captured here for debugging.

  • build/build.log – Output from the most recent gck build: pre-build commands, Docker builds, registry pushes, and workload restarts. Check this file first when a build step fails.
  • delete.log – Output from the most recent gck delete.
  • <context-path>/install.log – Output from gck create for a given context. The context path uses _ as a separator (e.g. gravitee-io_apim/install.log).
  • <context-path>/patch.log – Output from gck patch for a given context.

When a component fails to install or times out, the log file usually contains the Helm or kubectl error that explains why. Check it first before diving into kubectl commands.

mirrors/#

Data and configuration for image mirror proxies.

  • data/ – Cached image layers, persisted across cluster lifecycles. Mirror containers are stopped when the last gck cluster is deleted, but this data is kept.
  • hosts/ – Generated hosts.toml files that configure containerd on Kind nodes to pull through the local mirrors.

See Container Images for how to enable mirrors.

preload/#

Cached image layers for the preload registry. Like mirrors/, this data persists across cluster lifecycles – when you delete and recreate a cluster, previously pushed images are still available, and only changed layers need to be re-pushed. Images superseded by a newer push of the same tag are removed after each gck create push, or on demand with gck clean preload.

See Container Images – Image preloading for details.

preload.lock#

A lock file that coordinates gck commands sharing the preload registry. gck create, gck build and gck patch hold it shared while they push to the registry – gck create until it finishes – and garbage collection or the deletion of the last cluster needs it exclusively, since both stop the registry. The operating system releases the lock when a command exits, even if it crashes, so the file never needs to be removed by hand.

pids/#

PID files for background processes managed by gck:

  • cpk.pid – The cloud provider controller that assigns IPs to LoadBalancer Services.
  • dns.pid – The local DNS server.

These processes are started automatically by gck create and stopped by gck delete when no clusters or DNS records remain. You shouldn’t need to manage them manually.