gluon documentation

CNCF-grade planning docs

Compile policy-aware intent into execution DAGs you can review, diff, and run anywhere.

gluon separates desired state, composition logic, and runtime execution. Platform teams define intent once, validate it against schemas, bind it to reusable compositions, and materialize a deterministic plan that can run on a local shell, inside Docker, or through a GitHub Actions-compatible backend.

Start with the quick startRead the compiler pipeline

Intent stays declarative

Keep policy, environment defaults, and component subscriptions in intent files instead of leaking execution details into app repos.

Compositions stay reusable

Each composition package exports self-describing composition documents, so platform teams can evolve execution contracts centrally and ship them as local, archived, or OCI-hosted sources.

Plans stay deterministic

The generated plan is an immutable DAG with explicit jobs, steps, dependencies, retries, and state-file metadata.

Runtimes stay swappable

Compile once, then preview or execute through the local shell, a Docker runner, or GitHub Actions compatibility mode.

What gluon is for

Use gluon when you need a planner that can scale from a single repository to a platform estate without collapsing intent, validation, and execution into one format.

• Define desired state in intent.yaml plus discovered component.yaml files.
• Declare composition sources in intent.yaml and lock their resolved digests beside the intent.
• Validate platform contracts through JSON schema.
• Bind component types to reusable compositions exported from packages.
• Render a reviewable plan.json before anything executes.
• Run the plan in dry-run or execute mode with explicit backend selection.

Mental model

intent.yaml + component.yaml + composition packages
          ↓
      load, normalize, validate
          ↓
    resolve and lock composition sources
          ↓
  expand environment × component matrix
          ↓
  bind jobs and resolve dependencies
          ↓
      render immutable plan.json
          ↓
   dry-run or execute with a runner

Desired state

Intent and components

Intent declares environments, group-level policy, discovery roots, inline components, and change-scoping inputs. Component manifests declare type, inputs, labels, overrides, and dependencies.

Execution contract

Compositions and schemas

Each composition source exports typed Composition documents with an input schema, explicit default job, and portable job definitions. That keeps platform logic versioned and reusable.

Compiled artifact

Plan DAG

The plan records explicit jobs, step order, phase boundaries, dependencies, and runtime hints. It is the artifact you diff, archive, and execute.

Typical workflow

./gluon compositions lock --intent examples/intent.yaml

./gluon validate \
  --intent examples/intent.yaml

./gluon plan \
  --intent examples/intent.yaml \
  --output /tmp/gluon-plan.json

./gluon run --plan /tmp/gluon-plan.json

The default run mode is a dry-run, so teams can inspect the resolved jobs and steps before enabling --execute.

The lock command and planning flow write examples/.gluon/compositions.lock.yaml, which records the resolved composition digests used for the compiled plan.

How to read these docs

Start here

Getting started

Install the CLI, compile the example intent, and inspect the generated plan before executing anything.

Then learn

Concepts and architecture

Understand the separation between intent, compositions, plans, and runners before authoring your own platform contracts.

Then operate

CLI and reference

Use the command reference, schema reference, and environment variable matrix when integrating gluon into CI or platform automation.

Next steps

1. Follow the installation guide.
2. Run the repository-backed quick start.
3. Read intent model and plan DAG before writing new compositions.