All gck commands in one place. Every command respects the global flags listed at the bottom of this page.
gck create#
Create a Kind cluster and deploy the components defined by your context.
gck create
gck resolves the config chain (user-level $GCK_HOME/gck.yaml merged with your project gck.yaml), fetches contexts from the registry, creates the Kind cluster, and installs components in dependency order. If no registry or context is configured, only the bare cluster is created.
When features like load balancers, Gateway API, or DNS are enabled, gck sets them up automatically after the cluster is ready.
Before creating anything, gck checks the local files and environment variables that secrets and config maps are built from. A missing input that is not marked onMissing: ignore stops the command right away, naming the component and resource, instead of failing once the cluster is half installed. gck patch runs the same check on the components it upgrades.
Flags#
| Flag | Description |
|---|---|
--config <path> | Project-level config file. Defaults to ./gck.yaml when present. |
--registry <url> | Registry URL. Overrides the value from config. |
--from <path> | Context path to compose. Repeatable. Overrides the from list from config. |
--skip-preload | Skip image preloading even when images.preload is configured. |
Context flags#
Contexts can define optional flags that customize the deployment. These are extra --flag-name options defined by the context maintainer as gck--{flag-name}.yaml patch files.
gck create --from gravitee-io/apim --disable-portal --disable-ui --disable-analytics
Each flag merges a patch on top of the resolved context before deployment. Flags are cumulative – you can combine as many as needed. Passing an unknown flag produces an error listing the available flags for that context.
See Context Format – Context flags for how to author flag files.
Alternatives#
--use-* flags pick one implementation per group, such as the datasource and the analytics backend of APIM. The default member of each group applies when you pass none:
gck create --from gravitee-io/apim --use-mongodb --use-opensearch
Passing two members of the same group fails (--use-jdbc-mysql and --use-mongodb are mutually exclusive (group datasource)), and so does selecting a member of a group the context pins. Plain flags are applied after the alternatives, so --disable-analytics turns analytics off whichever backend is selected. In your gck.yaml, use: [mongodb, opensearch] selects the same members; a --use-* flag on the command line overrides the file’s member of its group. A member is selected by name in every group that has one: composing gravitee-io/apim and gravitee-io/am, whose datasource groups both offer MongoDB, --use-mongodb puts both on it.
A member can turn other flags on. --use-dbless runs the APIM gateway without a database and implies --disable-ui and --disable-analytics, so no console, portal or Elasticsearch is deployed; flags that need the management API, such as --enable-bridge, fail alongside it. gck info marks implied and conflicting flags for the current selection.
See Context Format – Alternatives for how to author them.
gck info#
Show what a context gives you without creating a cluster: its components, its alternatives with their defaults, its context flags, and the features it enables. Use it to discover what a context supports before running gck create.
gck info [context...] [--use-* ...] [--enable-* ...]
Name the contexts to compose as arguments, the same as repeated --from, or leave both out to use the config file’s from. Passing both arguments and --from is an error.
gck info gravitee-io/apim
gck info gravitee-io/apim --use-mongodb --enable-keycloak
gck info gravitee-io/apim a2a/standalone
Context flags preview another selection. --use-* switches the member of a group; --enable-* and --disable-* are applied as gck create applies them, so the component list includes what they add, and a flag that gck create would refuse (two members of one group, a missing requires, a conflicts) fails here with the same error.
What each section shows:
| Section | Content |
|---|---|
| Context | The contexts composed, in order |
| Components | The components that would be installed, with the flags applied |
| Alternatives | Each group and its members. * marks the selected member, (default) the default one, and (off: --flag) a group a flag disables. A group a composing context pins with use: is not shown. Two composed contexts that each declare a group of the same name get one entry each, named after the context: datasource (gravitee-io/apim). |
| Flags | The plain context flags. (implied by --x) marks a flag a selected member implies, (needs --x) a flag that requires one, and (not with --x) one that conflicts with it. |
| Features | lb, gateway and dns as the composition sets them |
| Usage | The gck create command for what was previewed |
Example output#
$ gck info gravitee-io/apim --use-mongodb
Context
Path: gravitee-io/apim
Components
- elasticsearch
- mongodb
- license
- tls-server
- apim
Alternatives
analytics
* --use-elasticsearch Store analytics in Elasticsearch (default)
--use-opensearch Store analytics in OpenSearch
datasource
--use-dbless No datasource: the gateway runs DB-less, configured from Kubernetes resources through GKO
--use-jdbc-mssql Store APIM data in Microsoft SQL Server over JDBC
--use-jdbc-mysql Store APIM data in MySQL over JDBC
--use-jdbc-postgres Store APIM data in PostgreSQL over JDBC (default)
* --use-mongodb Store APIM data in MongoDB
Flags
--disable-portal Disable the developer portal UI
--disable-ui Disable both Console and Portal UIs
--enable-bridge Enable bridge architecture: management API serves as bridge, gateway syncs through it
...
--disable-analytics Disable analytics: no Elasticsearch or OpenSearch, no analytics reporters
--enable-opensearch-dashboards Deploy OpenSearch Dashboards alongside OpenSearch (needs --use-opensearch)
Features
lb: disabled
gateway: disabled
dns: disabled
Usage
gck create --from gravitee-io/apim --use-mongodb
gck build#
Build local Docker images, push them to the cluster’s preload registry, and restart matching workloads. See the Developer Loop guide for a walkthrough.
gck build
gck build gateway console-ui
gck build --create --skip-pre gateway
Build entries are defined in the builds section of gck.yaml. When called without arguments, all entries are built. Pass one or more names to build a subset.
Flags#
| Flag | Description |
|---|---|
--create | Create the cluster if it doesn’t exist, then build. The context flags and --use-* alternatives passed to build apply to that creation. With an existing cluster, --create and the context flags have no effect. |
--skip-pre | Skip pre-build commands (pre), go straight to docker build. |
--no-restart | Build and push but don’t restart workloads. |
--name <cluster> | Target a specific cluster. Defaults to kind.name from the resolved config. |
Build logs#
All build output (pre-build commands, docker build) is written to ~/.gck/logs/build/build.log. On failure, gck prints the path so you can inspect the full output.
gck patch#
Upgrade components on a running cluster. There are two modes:
- With a patch file – merges the file into the resolved context and upgrades only the components listed in the file.
- With
--setonly – re-renders the resolved context with new template variable values and upgrades all components.
Both modes can be combined.
gck patch upgrade.yaml
gck patch upgrade.yaml --dry-run
gck patch --set imageTag=4.11.0 --set helmVersion=4.11.0
gck patch upgrade.yaml --set imageTag=4.11.0
Inherited context#
gck patch reuses the context the cluster was created with, so you only pass what changes. The from contexts, --registry, the context flags (e.g. --disable-analytics), the member of each alternative group (defaults included), and the --set overrides captured at gck create are read back from the saved cluster state (~/.gck/clusters/<name>.yaml) and applied automatically. Patch-time inputs take priority: --from / --registry override the stored values, per-key --set overrides win, and context flags passed to patch are added to the inherited ones.
Alternatives are the exception: a patch cannot switch implementation. Passing a --use-* flag that changes the member of any group fails, including a member another composed context was created with – delete the cluster and create it again with the new selection.
This keeps an upgrade small – it only needs the deltas:
gck create --from gravitee-io/apim --use-mongodb --disable-analytics \
--set imagePrefix=ghcr.io/acme --set imageTag=4.11 --set helmVersion=4.11.0
gck patch --name gravitee --set imageTag=4.12 --set helmVersion=4.12.0
The patch above keeps --use-mongodb, --disable-analytics, imagePrefix, and the from context from create. A cluster created by an older gck (no saved state) falls back to the previous behaviour, where flags and --set must be repeated on every patch.
How it works#
- Inherit + resolve context – gck reads the saved state for the target cluster and reuses the create-time
from,--registry, context flags and--setoverrides (patch-time inputs win), then resolves the registry context exactly asgck createdoes. - Verify cluster – gck checks that the target Kind cluster is running.
- Load patch file (when provided) – the patch file is loaded (same format as
gck.yaml). - Merge – patch components (if any) are merged on top of the resolved context using the standard merge rules .
- Upgrade – when a patch file is given, only components named in it are upgraded. When using
--setalone, all components are upgraded. - Readiness – gck waits for upgraded components that have
conditions.ready: true.
Patch file format#
The patch file uses the same format as gck.yaml. Only components, helm.repos, and images.preload are relevant – other fields are ignored.
Upgrade image tags#
components:
- name: my-app
helm:
values:
gateway:
image:
tag: "2.1.0"
api:
image:
tag: "2.1.0"
Change a chart version#
components:
- name: my-app
helm:
version: "2.1.0"
Add a value file overlay#
components:
- name: my-app
helm:
valueFiles:
- ./staging-overrides.yaml
Value file paths are resolved relative to the directory containing the patch file.
Patch a k8s manifest component#
components:
- name: custom-routes
k8s:
manifestFiles:
- ./updated-routes.yaml
Set-only mode#
When the registry context uses template variables (see Composing Contexts – Overriding variables
), you can upgrade without a patch file by passing new --set values:
# Create the cluster at version 4.10
gck create --from gravitee-io/apim \
--set imageTag=4.10.0 --set helmVersion=4.10.0
# Upgrade to 4.11 -- no patch file needed
gck patch --set imageTag=4.11.0 --set helmVersion=4.11.0
In this mode, the resolved context is re-rendered with the new variable values and all components are upgraded. Use --dry-run to preview the changes first.
Typical workflow#
# Create the cluster with the current version
gck create --set imageTag=4.10.0
# Run tests against the current version
./run-tests.sh
# Upgrade to the new version
gck patch --set imageTag=4.11.0
# Run tests against the new version
./run-tests.sh
# Tear down
gck delete
Image preloading#
When the cluster was created with image preloading enabled, the Kind nodes are already configured to pull from the local gck-preload registry. Adding images.preload.refs to your patch file pre-stages images before upgrading, so pods start faster:
images:
preload:
refs:
- myrepo/my-app:2.1.0-rc1
- myrepo/my-api:2.1.0-rc1
components:
- name: my-app
helm:
values:
image:
tag: 2.1.0-rc1
If no preload registry is running, gck prints a warning and proceeds normally.
Dry-run mode#
Use --dry-run to preview what a patch would change without applying anything:
gck patch upgrade.yaml --dry-run
When --dry-run is active:
- Helm components run
helm upgrade --dry-run=server– the chart is rendered and validated by the API server without creating the release - Kubernetes manifest components run
kubectl apply --dry-run=server– objects are validated without persisting - Readiness checks are skipped since no resources are actually deployed
- Colored diff output shows exactly what would change: added lines in green, removed lines in red
This is especially useful in CI pipelines:
gck patch upgrade.yaml --dry-run
gck patch upgrade.yaml
Flags#
| Flag | Description |
|---|---|
--name <cluster> | Name of the cluster to patch. Defaults to kind.name from the resolved config. |
--set <key=value> | Override a template variable. Repeatable. When used without a patch file, all components are upgraded. |
--dry-run | Preview changes without applying. Uses server-side dry-run for both Helm and Kubernetes resources. |
--skip-preload | Skip image preloading even when images.preload is configured. |
gck delete#
Tear down a cluster and clean up all associated resources: the Kind cluster, load balancer containers, DNS records, mirror proxies, and the preload registry.
gck delete
gck delete my-cluster
How it works#
- Resolve target – gck determines which cluster to delete (see Target resolution below).
- DNS records – Removes the cluster’s DNS record file.
- Load balancer containers – Stops and removes Docker containers created by the cloud provider controller.
- Kind cluster – Deletes the Kind cluster, removing all namespaces, Helm releases, and applied manifests.
- Image registries – Stops the preload registry and mirror proxy containers once no other gck cluster is running and no
gck createis in progress. Every cluster pulls from the same ones, so they keep running while another cluster still needs them. Their data in$GCK_HOMEis kept either way. - Background processes – Stops the cloud provider controller and DNS server when no clusters or DNS records remain.
- State file – Removes the cluster’s state file from
$GCK_HOME/clusters/.
Target resolution#
gck delete doesn’t need the original gck.yaml or registry to be available. It uses state files to find and clean up the cluster. See Directory Layout – clusters/
for how target resolution and best-effort cleanup work.
gck list#
List all gck-managed clusters with their status.
gck list
Shows a table with the cluster name, creation date, context paths, active context flags (selected alternatives first, defaults included), and whether the cluster is currently running.
Example output#
NAME CREATED FROM FLAGS STATUS
gravitee 2026-03-23 14:00 gravitee-io/apim --use-elasticsearch, --use-mongodb, --disable-portal running
pg-standalone 2026-03-22 10:30 postgresql/standalone - stopped
gck describe#
Show detailed information about a cluster: features, active load balancers, and DNS state. Information is read from the persisted cluster state, not from the current config.
gck describe
gck describe my-cluster
When no name is given and only one cluster exists, it is selected automatically. When multiple clusters exist, gck asks you to specify one (use gck list to see them).
What it shows#
Cluster – The cluster name, creation date, context paths, and any context flags that were active at creation time.
Features – Whether load balancers, Gateway API, and DNS are enabled. For Gateway API, shows the channel (standard or experimental) when the config sets one. For DNS, shows the domain and port.
Load Balancers – Lists active load balancer containers and their IPs. gck queries Docker directly for containers associated with the cluster, so this reflects the actual running state even if the original config is no longer available.
DNS – Four pieces of information:
- Resolver: whether OS-level DNS routing is configured (i.e. whether
gck setup dnshas been run) - Server: whether the local DNS server process is running
- Cluster: whether the cluster’s CoreDNS resolves the domain, so pods reach the same hostnames
- Records: all registered hostname-to-IP mappings, grouped by cluster
Example output#
Cluster
Name: gravitee
Created: 2026-09-27 10:24
From: gravitee-io/gamma
Flags: --use-mongodb
Features
lb: enabled
gateway: enabled
dns: enabled (domain: gck.local, port: 15353)
Load Balancers
bc1e32bc2451 → 172.18.0.4
DNS
resolver: configured for gck.local
server: running on 127.0.0.1:15353
cluster: CoreDNS synced for gck.local
records:
am-console.gravitee.gck.local → 172.18.0.4 (gravitee)
apim-api.gravitee.gck.local → 172.18.0.4 (gravitee)
apim-console.gravitee.gck.local → 172.18.0.4 (gravitee)
gamma-console.gravitee.gck.local → 172.18.0.4 (gravitee)
gck validate#
Validate gck.yaml and context flag files (gck--*.yaml) against the configuration schema. Catches typos, unknown fields, and type mismatches before you deploy.
gck validate
gck validate registry/kafka/standalone/gck.yaml
gck validate registry/
When given a directory, gck walks it recursively and validates every gck.yaml and gck--*.yaml file it finds. When no argument is given, it validates ./gck.yaml in the current directory.
Context flag files are also checked for:
- A kebab-case name and a non-empty
description. - The fields their kind allows: an alternative (
gck--use-*.yaml) declares agroupand may declaredefaultandimplies; a plain flag may declarerequires,conflictsanddisables.impliesnames plain flags only. - Exactly one
default: truemember per alternative group of a directory.
Exit code is non-zero when any file fails validation, making it suitable for CI pipelines and pre-commit checks.
Flags#
| Flag | Description |
|---|---|
--tags <file> | Also check the tags in the front matter of each README.md next to a gck.yaml against the vocabulary in <file>. Skipped when omitted. |
gck clean preload#
Remove superseded images from the preload registry in $GCK_HOME/preload: every manifest no tag points at, and every layer only those manifests used.
gck clean preload
gck clean preload --dry-run
Pushing a mutable tag (latest, nightly builds) again moves the tag to the new image and leaves the previous one in storage. gck create collects this garbage after each push, so you only need this command to reclaim space left by gck build and gck patch, or to see what would be removed.
Tagged images are never removed, including the platform images of a multi-platform index. The preload registry container is stopped during the collection and restarted afterwards if it was running; running clusters pull from upstream registries for those few seconds.
If another gck command is pushing to the preload registry, gck clean preload waits for it to finish first. gck create skips its own collection in that case and leaves the garbage to a later run, so it never waits on another command.
Flags#
| Flag | Description |
|---|---|
--dry-run | List the manifests that would be removed and the space that would be reclaimed, without stopping the registry. |
gck setup dns#
Configure your operating system to forward *.gck.local queries to the local DNS server. This is a one-time setup that requires sudo.
gck setup dns
- macOS: creates
/etc/resolver/gck.local(persists across reboots) - Linux: configures
systemd-resolvedon the loopback interface (runtime only)
After this, gck create and gck delete run without sudo.
gck teardown dns#
Remove the OS-level DNS routing created by gck setup dns.
gck teardown dns
gck refresh dns#
Re-collect DNS records from the running cluster. Use this after deploying additional Gateways or LoadBalancer Services that weren’t present during gck create.
gck refresh dns
The running DNS server picks up the updated records immediately.
Global flags#
These flags are available on all commands:
| Flag | Description |
|---|---|
--config <path> | Project-level config file to merge on top of the user-level base ($GCK_HOME/gck.yaml). Defaults to ./gck.yaml when present. |
--registry <url> | Registry URL (e.g. file://./registry or https://…). Overrides the value from config. |
--from <path> | Context path to compose (e.g. elastic/elasticsearch/standalone). Repeatable. Overrides the from list from config, and drops the config’s use, which selects members of the config’s contexts. |
--set <key=value> | Set a template variable. Repeatable. Overrides defaults declared in the vars block of any gck.yaml. See Template variables
. |
Template variables#
gck.yaml files support Go template expressions. Declare variables with defaults in a vars block and reference them with {{ .variableName }}:
vars:
helmVersion: ""
imageTag: "latest"
components:
- name: apim
helm:
chart: graviteeio/apim
version: "{{ .helmVersion }}"
values:
gateway:
image:
tag: "{{ .imageTag }}-debian"
ui:
image:
tag: "{{ .imageTag }}"
Override at deploy time with --set:
gck create --set imageTag=4.12.0
gck patch --set imageTag=4.12.0 --set helmVersion=4.12.0
gck patch upgrade.yaml --set imageTag=4.12.0
Precedence#
varsdefaults in the gck.yaml file (lowest)--setvalues from the CLI (highest)
Template functions#
| Function | Usage | Description |
|---|---|---|
env | {{ env "HOME" }} | Returns the value of an environment variable. |
default | {{ .myVar | default "fallback" }} | Returns the fallback when the pipeline value is empty. |
required | {{ .myVar | required "myVar must be set" }} | Returns the value or fails with the given message when empty. |
Scope#
Templating applies to every gck.yaml in the pipeline: user config, $GCK_HOME/gck.yaml, patch files, context flag overlays, and registry context files. Each gck.yaml is templated with its own vars defaults and the --set overrides. Registry contexts also take the path-scoped overrides of the contexts composing them, and context flag files see the vars of the composition they apply to (see Context Format – Templating in composed contexts
).