Commands

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#

FlagDescription
--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-preloadSkip 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:

SectionContent
ContextThe contexts composed, in order
ComponentsThe components that would be installed, with the flags applied
AlternativesEach 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).
FlagsThe 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.
Featureslb, gateway and dns as the composition sets them
UsageThe 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#

FlagDescription
--createCreate 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-preSkip pre-build commands (pre), go straight to docker build.
--no-restartBuild 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 --set only – 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#

  1. Inherit + resolve context – gck reads the saved state for the target cluster and reuses the create-time from, --registry, context flags and --set overrides (patch-time inputs win), then resolves the registry context exactly as gck create does.
  2. Verify cluster – gck checks that the target Kind cluster is running.
  3. Load patch file (when provided) – the patch file is loaded (same format as gck.yaml).
  4. Merge – patch components (if any) are merged on top of the resolved context using the standard merge rules .
  5. Upgrade – when a patch file is given, only components named in it are upgraded. When using --set alone, all components are upgraded.
  6. 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#

FlagDescription
--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-runPreview changes without applying. Uses server-side dry-run for both Helm and Kubernetes resources.
--skip-preloadSkip 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#

  1. Resolve target – gck determines which cluster to delete (see Target resolution below).
  2. DNS records – Removes the cluster’s DNS record file.
  3. Load balancer containers – Stops and removes Docker containers created by the cloud provider controller.
  4. Kind cluster – Deletes the Kind cluster, removing all namespaces, Helm releases, and applied manifests.
  5. Image registries – Stops the preload registry and mirror proxy containers once no other gck cluster is running and no gck create is in progress. Every cluster pulls from the same ones, so they keep running while another cluster still needs them. Their data in $GCK_HOME is kept either way.
  6. Background processes – Stops the cloud provider controller and DNS server when no clusters or DNS records remain.
  7. 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 dns has 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 a group and may declare default and implies; a plain flag may declare requires, conflicts and disables. implies names plain flags only.
  • Exactly one default: true member 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#

FlagDescription
--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#

FlagDescription
--dry-runList 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-resolved on 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:

FlagDescription
--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#

  1. vars defaults in the gck.yaml file (lowest)
  2. --set values from the CLI (highest)

Template functions#

FunctionUsageDescription
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 ).