This page is for context authors – the people who create and maintain registry contexts for others to use. If you’re just using contexts, see Composing Contexts .
Anatomy of a context#
A context lives at {registry}/{context_path}/ and must contain a gck.yaml. At minimum, it declares components to deploy:
helm:
repos:
- name: bitnami
url: https://charts.bitnami.com/bitnami
components:
- name: mongodb
type: helm
namespace: default
helm:
chart: bitnami/mongodb
version: "16.4.0"
valueFiles:
- values.yaml
File paths in valueFiles and manifestFiles are resolved relative to the context directory.
Component types#
Helm components#
The default type. Installs a Helm chart:
components:
- name: my-app
type: helm
namespace: my-ns
helm:
chart: myrepo/my-app
version: "2.0.0"
valueFiles:
- values.yaml
values:
replicas: 1
Kubernetes manifest components#
Deploy plain Kubernetes resources by setting type: k8s. You can use inline manifests, file references, or both:
components:
- name: routes
type: k8s
namespace: my-ns
k8s:
manifestFiles:
- gateway.yaml
- httproutes.yaml
manifests:
- apiVersion: v1
kind: Service
metadata:
name: my-service
spec:
type: ClusterIP
ports:
- port: 8080
File-based resources are applied first, then inline manifests. Both component types participate in the same dependency graph.
Composition with from#
Contexts can compose other contexts. List the parent paths in from:
from:
- mongodb/standalone
- elastic/elasticsearch/standalone
components:
- name: my-app
requires:
- component: mongodb
- component: elasticsearch
helm:
chart: myrepo/my-app
Parents are resolved left-to-right, then local overrides are applied on top using the standard merge rules .
Cross-registry composition#
By default, from entries are resolved against the same registry. To compose from a different registry:
registry: https://other-registry.example.com
from:
- org/product/base
Relative file:// paths are resolved relative to the child context’s directory.
Abstract contexts#
Mark a context as abstract: true when it’s a shared base that shouldn’t be deployed on its own:
abstract: true
helm:
repos:
- name: myrepo
url: https://charts.example.com
components:
- name: app
helm:
chart: myrepo/app
version: "2.0.0"
Attempting to deploy an abstract context directly with gck create produces an error. Concrete variants must compose from it via from.
Default variant resolution#
Add a .default file next to variant directories to set the default:
echo "standalone" > registry/mongodb/.default
When a user specifies from: [mongodb], gck reads .default and resolves it to mongodb/standalone. Defaults chain across multiple levels. A directory with its own gck.yaml is resolved directly and its .default, if any, is ignored – a context may also hold child contexts in subdirectories.
Merge semantics#
When contexts are composed, each top-level field is merged as follows:
kind– Scalar fields: child wins if set.nodes: child replaces the list, butextraPortMappingsare union-merged by(containerPort, protocol).containerdConfigPatches: child replaces entirely.components– Matched by name. Helm chart/version: child wins. Value files: appended. Values: deep-merged. Manifest files: appended. Manifests: union by resource identity. Secrets/configMaps: matched by name, child replaces; new names appended. Requirements: appended and deduplicated. Unmatched components are appended.helm.repos– Deduplicated by name; child wins on conflict.features– Each feature block is replaced as a whole if the child defines it; otherwise inherited.images–preload: merge mode (default) unionsrefsandskip; replace mode uses only the child’srefs.mirrors: child wins if set.
Overriding service networking#
When your context composes from a child that exposes services via NodePort, you might need to switch them to ClusterIP because your context handles networking differently.
For Helm components, override the values and explicitly clear nodePort:
components:
- name: child-service
helm:
values:
service:
type: ClusterIP
nodePort: null
For k8s manifest components, provide a full replacement Service manifest. Manifests are merged by resource identity, so your Service replaces the child’s entirely.
Template variables#
Context authors can parameterize their gck.yaml with Go template expressions. Declare variable 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"
api:
image:
tag: "{{ .imageTag }}-debian"
ui:
image:
tag: "{{ .imageTag }}"
images:
preload:
refs:
- "graviteeio/apim-gateway:{{ .imageTag }}-debian"
- "graviteeio/apim-management-api:{{ .imageTag }}-debian"
- "graviteeio/apim-management-ui:{{ .imageTag }}"
Users override defaults at deploy time:
gck create --set imageTag=4.12.0
Rules#
- Variable names use camelCase (
imageTag,helmVersion, notimage_tag). - An entry is a var declaration when it is a string or has a
defaultkey (with an optionaldescription). Any other map is a path segment: nested entries are overrides of a parent’s vars . - A default may use the template functions, but not other vars:
default: '{{ env "HOME" }}/opt/gravitee/license.key'renders, anddefault: '{{ .base }}/license.key'fails with an error naming the var. The same holds for--setvalues. Write a literal{{as{{ "{{" }}. - Undefined variables with no default cause an error.
- Use the
envfunction to reference environment variables:{{ env "HOME" }}. - Use
defaultfor inline fallbacks:{{ .myVar | default "fallback" }}. - Use
requiredfor mandatory variables:{{ .licenseKey | required "licenseKey must be set via --set" }}.
Templating in composed contexts#
Each context’s gck.yaml is templated during resolution with its own vars: its defaults, the path-scoped overrides the contexts composing it set, then --set. It does not see the vars its parents or children declare; --set reaches every level:
# Parent: vars: { dbVersion: "15" } uses {{ .dbVersion }}
# Child: vars: { imageTag: "latest" } uses {{ .imageTag }}
# --set dbVersion=16 --set imageTag=v2 overrides both
Context flag files see more. An alternative is templated with the vars of its context and of every context that context composes. A plain flag’s patch is templated once the whole composition is resolved: the vars of every composed context (on a shared name, a context wins over those it composes, and a later from entry over an earlier one), then the flag’s own vars defaults, then --set.
Context flags#
Context flags let maintainers expose optional toggles without creating separate registry directories for every combination. A flag is defined by placing a gck--{flag-name}.yaml patch file alongside the context’s gck.yaml.
File format#
Flag files use the same schema as gck.yaml, with a description field that documents what the flag does:
description: "Disable the developer portal UI"
components:
- name: apim
helm:
values:
portal:
enabled: false
Naming convention#
Flag file names must follow the pattern gck--{flag-name}.yaml where flag-name is lowercase kebab-case: ^[a-z0-9]+(-[a-z0-9]+)*$. Users activate flags with --flag-name on the CLI:
gck create --from gravitee-io/apim --disable-portal --disable-ui
The use- prefix is reserved for alternatives
.
Inheritance from abstract parents#
Flags defined on an abstract context are inherited by all concrete contexts that compose from it via from. A child context can override an inherited flag by providing its own gck--{name}.yaml with the same name.
Flags that compose contexts#
A flag that needs other contexts – a broker, a datastore – lists them in from. While the flag is active, they are composed ahead of the declaring context during resolution, like an alternative
’s, and the flag’s path-scoped vars overrides reach them. The flag’s own patch is applied afterwards with the other flags, so it has the last word over the declaring context’s values:
# gck--enable-streaming.yaml
description: "Deploy a Kafka broker and wire the app to it"
from:
- kafka/standalone
vars:
kafka:
standalone:
imageTag:
default: "3.9"
components:
- name: app
helm:
values:
streaming:
bootstrapServers: kafka:9092
Like an alternative’s, a flag’s from is read before templating and must be literal.
Cumulative application#
Multiple flags can be combined. Each flag’s patch is merged on top of the resolved context in the order they appear on the command line, using the same merge rules as context composition. Flags are applied after alternatives, so a flag always has the last word over the selected implementation.
Required local files#
Secrets and config maps built from local files or env vars fail the deployment when the input is missing (onMissing: fail, the default) or skip themselves (onMissing: ignore). gck create and gck patch check every non-ignored input before touching the cluster. Because secrets merge by name, a flag can make an optional input mandatory by redeclaring it:
# gck--enable-signing.yaml
description: "Sign responses (needs the signing key)"
components:
- name: keys
k8s:
secrets:
- name: signing-key
fromFile: "{{ .signingKeyFile }}"
onMissing: fail
Requirements and conflicts#
A flag that only works with some other flag or alternative lists it in requires. gck create fails when a required name is not active; a default alternative counts as active:
description: "Deploy Kibana alongside Elasticsearch"
requires:
- use-elasticsearch
A flag that cannot work with one lists it in conflicts, and gck create refuses the combination:
description: "Enable bridge architecture: management API serves as bridge, gateway syncs through it"
conflicts:
- use-dbless
Disabling components#
Flags can fully exclude a component from deployment by setting enabled: false. When a component is disabled, it is not installed and any requires entries referencing it are silently dropped:
description: "No datasource: the gateway runs DB-less"
components:
- name: tls-server
enabled: false
- name: apim
helm:
values:
api:
enabled: false
APIM’s --use-dbless does this: the tls-server component is skipped entirely, and apim, which declares requires: [{component: tls-server}], proceeds without waiting for it. Disabling a component the composition does not contain is a no-op.
To remove a component an alternative
brings in, disable the whole group with disables
instead: the member is then never composed, so its host ports and notes go too.
Alternatives#
An alternative is a flag that picks one implementation among mutually exclusive ones, such as the datasource of a product. Alternatives sharing a group form a set: exactly one member is applied on every gck create, the default: true member unless the user selects another, and none while a flag in force disables
the group.
# gck--use-mongodb.yaml
description: "Store APIM data in MongoDB"
group: datasource
from:
- mongodb/standalone
vars:
mongodb:
standalone:
imageTag:
default: "7"
components:
- name: apim
helm:
values:
mongo:
uri: mongodb://mongodb:27017/apim
| Field | Meaning |
|---|---|
group | Required. Name of the set of mutually exclusive members. |
default | Marks the member applied when the user selects none. Exactly one per group. |
from | Contexts composed when this member is selected, ahead of the declaring context’s own from. Plain flags may declare it too (see Flags that compose contexts
). |
vars | Var declarations and path-scoped overrides, merged with the declaring context’s. An alternative’s default wins over the context’s for the same name. |
implies | Plain flags turned on whenever this member is selected. See Cascading . |
The file name must be gck--use-{member}.yaml, and only alternatives may use the use- prefix.
Resolution#
Alternatives are applied where they are declared, while the context is resolved. Selecting --use-mongodb on a context with from: [gravitee-io/apim/base] resolves it as if it declared from: [mongodb/standalone, gravitee-io/apim/base], with the member’s body merged after the context’s own. Members that are not selected are never composed. Groups are applied in group-name order.
An alternative’s from is read before templating and must be literal. The rest of the file is rendered once the declaring context is resolved, with the composition’s effective vars – the same vars a plain flag file sees, so a member can use {{ .imagePrefix }} declared by an abstract base.
A context that composes one with alternatives inherits them: a context with from: [gravitee-io/am] offers AM’s --use-* flags unless it pins
them, as gravitee-io/gamma does. A context cannot redeclare an alternative or a group it inherits.
Cascading#
Selecting a member sometimes makes other features meaningless. Three fields express that in the files:
| Field | On | Effect |
|---|---|---|
implies | alternative | Plain flags, of this context or one it composes, turned on whenever the member is selected, as if passed on the CLI. They are applied, saved with the cluster, and visible to hasFlag. |
disables | plain flag | Alternative groups switched off while the flag is in force: no member of the group is composed. |
conflicts | plain flag | Flags or alternatives the flag cannot be combined with. |
They chain. --use-dbless implies disable-ui and disable-analytics, and disable-analytics disables the analytics group, so a DB-less gateway composes no Elasticsearch at all:
# gck--use-dbless.yaml
description: "No datasource: the gateway runs DB-less, configured from Kubernetes resources through GKO"
group: datasource
from:
- gravitee-io/gko
implies:
- disable-ui
- disable-analytics
# gck--disable-analytics.yaml
description: "Disable analytics: no Elasticsearch or OpenSearch, no analytics reporters"
disables:
- analytics
A disables flag only switches off groups declared by the same context. Selecting a member of a disabled group explicitly (--use-opensearch --disable-analytics) is not an error: the disable wins and gck prints a warning.
Pinning#
Gamma composes AM but only works on MongoDB, so it locks AM’s datasource with use:
# registry/gravitee-io/gamma/gck.yaml
from:
- gravitee-io/am
use:
- mongodb
Gamma users can no longer pick an AM datasource: --use-jdbc-postgres fails.
use only locks groups of the contexts you compose. For a group your context declares itself, mark the member you want default: true; naming it in use is an error.
Members are named with or without the use- prefix in use. The same field in your own gck.yaml selects members the way --use-* flags do, without pinning: the groups stay visible, and a --use-* flag on the command line overrides the file’s member of its group.
Flags, alternatives or separate contexts#
Use flags for optional features within a context – things that can be toggled on or off without changing the fundamental nature of the deployment (e.g., disabling analytics, removing UIs, enabling debug mode).
Use alternatives for interchangeable implementations of something the stack always has (e.g., MongoDB vs PostgreSQL as the datasource, Elasticsearch vs OpenSearch for analytics).
Use separate context directories for fundamentally different topologies (e.g., GKO as a Gateway API controller vs the APIM chart, standalone vs clustered). A mode that only removes things – APIM without a database – is an alternative that implies the flags removing them.
Registry organization tips#
- Use the
org/product/variantconvention for discoverability - Extract shared config into
abstract: truebase contexts - Set
.defaultfiles so users can reference products without spelling out the full variant path - Offer interchangeable backends as alternatives on one product context rather than one directory per backend
- Include a
README.mdwith front matter (title,description,tags) – the site generator uses it for the registry browser - Add
notes.createdeclaring the endpoints this context exposes, plus any instructionsgck createshould print after a successful deploy. Notes are merged across every composed context into a single endpoints table, so declare only what this context owns and let variants inherit the rest. Usewhento gate a row on a context flag :
---
title: APIM
endpoints:
- name: APIM Portal
url: http://localhost:30081
when: '{{ not (hasFlag "disable-portal") }}'
---
Everything has been deployed in the `gravitee` namespace.
See Contributing – notes.create
for the full format and the checks that keep notes in sync with gck.yaml.