Bundle Reference

Use this when adding a new component to a bundle, debugging an unexpected resolved value, or building tooling that consumes the bundle. A bundle is a versioned, curated list of platform components and the default versions of each. Engineers pin against a bundle release for reproducible runs (CI), or against the moving edge for daily iteration. Forge resolves a bundle plus an optional override file into a concrete set of Helm releases, then applies them inside your per-engineer vCluster.

Top-level shape

apiVersion: platform.grnds.io/v1
kind: PlatformBundle
metadata:
  version: 0.4.0
  description: |
    Free-form description...
shared:
  nats: { ... }
  postgres: { ... }
  keycloak: { ... }
components:
  velocity: { ... }
  plugin-social: { ... }
  ...

Field	Type	Required	Notes
`apiVersion`	string	yes	Must equal `platform.grnds.io/v1`. Forge rejects other values.
`kind`	string	yes	Must equal `PlatformBundle`.
`metadata.version`	semver	yes	Source-of-truth for the bundle’s own version. release-please bumps this in lockstep with the git tag.
`metadata.description`	string	no	Human-readable.
`shared`	object	yes	Tailnet-exposed backends shared across all engineer vClusters.
`components`	map	yes	Map of release-name → BundleComponent.

`shared`

Backends that don’t run inside an engineer’s vCluster. Each in-vCluster service connects out via Tailscale to these endpoints.

The endpoints declared here are only reachable from the internal Grounds tailnet — a private Tailscale network for authorized engineers. External contributors won’t be able to resolve nats.dev / postgres.dev / keycloak.dev. The bundle composition is still publicly readable; only the runtime is gated.

shared:
  nats:
    tailnet: nats.dev
    port: 4222
    description: NATS JetStream — cross-service events and the KV store for player presence
  postgres:
    tailnet: postgres.dev
    port: 5432
    description: One database per engineer (`<handle>_<service>`); shared server
  keycloak:
    tailnet: keycloak.dev
    port: 443
    realm: grounds-test

Field	Type	Required	Notes
`<endpoint>.tailnet`	string	yes	MagicDNS hostname on the internal Grounds tailnet. The engineer must be on the tailnet and have the matching dev-routes ACL enabled.
`<endpoint>.port`	int	yes	TCP port at the endpoint.
`<endpoint>.description`	string	no	Human-readable.
`keycloak.realm`	string	yes for keycloak	Realm name. Currently `grounds-test`.

The shared block is informational — forge doesn’t push these values into helm values automatically. The component charts are responsible for connecting using the same names (e.g. the in-vCluster service-config chart has NATS_URL=nats://nats.dev:4222 baked into its env).

`components`

A map: each key is the Helm release name (also used as namespace-DNS-label inside the vCluster, so it must be a valid DNS-1123 label — lowercase, hyphens, no underscores). Each value is a BundleComponent:

components:
  plugin-social:
    type: plugin-velocity
    chart:
      url: oci://ghcr.io/groundsgg/charts/plugin-velocity-jar
      version: 0.1.0
    image: ghcr.io/groundsgg/plugin-social
    version: edge
    optional: false
    helm:
      resources:
        requests: { cpu: 50m, memory: 64Mi }
    devspace:
      workflow: jar-sync-pod-restart

`BundleComponent` fields

Field	Type	Required	Notes
`type`	string	yes	Component-type string. See below.
`chart.url`	string	yes	OCI Helm chart URL.
`chart.version`	semver	yes	Pinned Helm chart version.
`image`	string	yes	Container image without tag. Forge passes this as `image.repository` into helm values.
`version`	string	yes	Image tag — semver, `edge`, or any other ref. Passed as `image.tag`.
`optional`	bool	no, default `false`	When `true`, the component is not deployed by default. Override with `enabled: true` to bring it in.
`helm`	map	no	Free-form Helm values. See merging rules below.
`devspace.workflow`	string	no	Selects a DevSpace template when the component is overridden into `gradle-local` mode.

Component types

The type field is a string for forward-compat, but the platform-test environment understands these values:

Type	What it is	DevSpace workflow	Iter-Latency
`plugin-velocity-base`	The Velocity proxy itself	`jar-sync-pod-restart`	~10–20 s
`plugin-velocity`	A JAR plugin loaded by Velocity at startup	`jar-sync-pod-restart`	~10–20 s
`plugin-paper` (planned)	A JAR plugin loaded by Paper	`jar-sync-plugin-reload`	~5–15 s
`gamemode`	Minestom or Paper game-server	`jar-sync-pod-restart`	~10–20 s
`grpc-service`	Quarkus-based gRPC backend	`quarkus-dev`	~1–3 s
`utility`	Test/debug tooling (e.g. nats-recorder)	–	–

Forge uses type only for default-behavior decisions (today: which DevSpace workflow template to suggest). Adding a new type is a bundle PR, not a forge PR.

Helm value merging

The values forge passes to helm install for a component are produced by:

Start with the component's helm: block

Or {} if absent.

Inject image.repository + image.tag

Deep-merge { image: { repository: <component.image>, tag: <resolved-tag> } } on top.

Inject DevSpace pickup annotations (when gradle-local)

Deep-merge a podAnnotations block:

podAnnotations:
  grounds.gg/devspace-mode: gradle-local
  grounds.gg/devspace-project: ./plugin-social
  grounds.gg/devspace-artifact: build/libs/*-all.jar
  grounds.gg/devspace-reload: pod-restart
  grounds.gg/devspace-quarkus-dev: "true"   # only when devspace:true

Deep-merge rules:

Plain-object values are merged recursively.
Arrays are replaced wholesale (no list-merge).
Primitives are replaced.

helm.image.tag = "0.5.0" in the bundle is not a useful value — forge will overwrite it with the resolved tag. Pin via the version: field instead.

Override-File schema

Engineers write an override YAML and pass it to grounds cluster up --bundle X --override ./me.yaml. Schema:

bundle: 0.4.0    # bundle ref to apply against. --bundle on cmd-line wins.

overrides:
  <component-name>: <ComponentOverride>

<ComponentOverride> is a discriminated union — exactly one of these shapes:

image (default)
gradle-local
enabled: false

Use the bundle’s image but optionally override the tag.

overrides:
  velocity:
    mode: image
    tag: dev-fix-routing-123    # optional

Field	Type	Required	Notes
`mode`	`"image"`	yes
`tag`	string	no	Replaces the bundle’s `version:` for this component. Omit to keep the default.

Engineer’s local gradle project supplies the JAR (or runs Quarkus dev). Forge stamps DevSpace pickup annotations onto the deployed Pod so DevSpace can find the right Pod.

overrides:
  plugin-social:
    mode: gradle-local
    project: ./plugin-social
    artifact: build/libs/plugin-social-*.jar
    reload: pod-restart

overrides:
  service-social:
    mode: gradle-local
    project: ./service-social
    devspace: true   # → quarkus-dev workflow

Field	Type	Required	Notes
`mode`	`"gradle-local"`	yes
`project`	string	yes	Workspace-relative path. Used by DevSpace, not by forge directly.
`artifact`	string	yes (non-`devspace`)	Glob for the built JAR. Required by `jar-sync-pod-restart`.
`reload`	`"rcon-plugin-reload"` \| `"pod-restart"`	no	How DevSpace re-applies the new JAR. Default `pod-restart`.
`devspace`	bool	no	When `true`, switch to the `quarkus-dev` workflow (sub-second hot-reload).

Skip the component entirely.

overrides:
  paper-game:
    enabled: false

Field	Type	Required	Notes
`enabled`	`false`	yes	The literal `false`.

There’s intentionally no enabled: true form for non-optional components — they’re already on. For components with optional: true in the bundle (e.g. nats-recorder), enabled: true flips them on:

overrides:
  nats-recorder:
    enabled: true

Pod annotations

The fields project, artifact, reload, and devspace aren’t applied by forge — they’re echoed as Pod annotations for DevSpace to read on the engineer’s laptop. The annotations forge writes:

Annotation	Value
`grounds.gg/devspace-mode`	`gradle-local`
`grounds.gg/devspace-project`	the `project` value
`grounds.gg/devspace-artifact`	the `artifact` value
`grounds.gg/devspace-reload`	the `reload` value (only when set)
`grounds.gg/devspace-quarkus-dev`	`"true"` when `devspace: true`

Resolution algorithm

When forge gets (bundle, override-file):

Filter components

Drop everything where override.enabled === false. Drop optional: true components that aren’t explicitly enabled.

Resolve per remaining component

If override is mode: image with tag: replace imageTag with the override.
If override is mode: gradle-local: keep image+tag from bundle; mark mode for annotation injection later.
If no override: use bundle defaults.

Compute helm values

Deep-merge per the rules above.

Helm install

Best-effort, parallel-friendly. If one component’s chart is missing, the others still go through. Failed components are reported in the response body but don’t fail the call.

Adding a new component

Ensure the chart exists

Make sure the component-type’s Helm chart is in groundsgg/charts and published as an OCI artifact (or co-publish it in the same PR).

Add a components: entry to bundle.yaml

plugin-foo:
  type: plugin-velocity            # or whichever type
  chart:
    url: oci://ghcr.io/groundsgg/charts/plugin-velocity-jar
    version: 0.1.0
  image: ghcr.io/groundsgg/plugin-foo
  version: edge
  devspace:
    workflow: jar-sync-pod-restart

Mark optional if it shouldn't run by default

Add optional: true and document the opt-in in examples/.

Open the PR

release-please bumps the bundle version on merge.

Versioning

release-please drives the bundle version:

Commit type	Bump
`feat:`	minor
`fix:`	patch
`feat!:` / `BREAKING CHANGE:`	major

Engineers pin against bundle versions:

bundle: 0.4.0     # reproducible

bundle: main always tracks the latest commit on main — useful for daily iteration, not for CI.

Concepts

CLI

Gradle plugin

Internal — Grounds engineers only

Top-level shape

`shared`

`components`

`BundleComponent` fields

Component types

Helm value merging

Override-File schema

Pod annotations

Resolution algorithm

Adding a new component

Versioning

See also

Concepts

CLI

Gradle plugin

Internal — Grounds engineers only

Documentation Index

​Top-level shape

​shared

​components

​BundleComponent fields

​Component types

​Helm value merging

​Override-File schema

​Pod annotations

​Resolution algorithm

​Adding a new component

​Versioning

​See also

Top-level shape

`shared`

`components`

`BundleComponent` fields

Component types

Helm value merging

Override-File schema

Pod annotations

Resolution algorithm

Adding a new component

Versioning

See also