Design

Launcher — Design Document

Date: 2026-04-19 | Updated: 2026-10-04 | Status: Phase 3 shipped, Phase 5 gate met

1. Vision

Launcher is an OAM-inspired package manager for Kubernetes — a semantically richer alternative to Helm.

Where Helm templates Kubernetes manifests from Go template files and a flat values.yaml, launcher models deployments using OAM concepts (Applications, Components, Traits) as its package format, under launcher’s own API group. The result is a tool where application structure is explicit and typed, platform implementation choices are separated from application choices, and output is always static, GitOps-ready Kubernetes manifests.

Launcher defines its own native application model under launcher.gokure.dev/v1alpha1. OAM is the conceptual inspiration, not the API contract — launcher does not claim native API compatibility with core.oam.dev/v1beta1.

Launcher uses the kure library for Kubernetes resource generation.

2. Background — Origin in kure

Launcher originated as pkg/launcher inside the kure library — an early prototype of a declarative, file-based Kubernetes manifest generation pipeline. That prototype demonstrated the core idea (parametric package definitions, patch-based composition) but was not yet OAM-aware and did not have a clear separation between platform and application concerns.

The decision to extract launcher into its own repository reflects two things:

1. Launcher is an application (a CLI tool with its own user, design space, and release cadence), not a library component. It does not belong inside kure.
2. The design direction is changing: the next iteration is built around OAM rather than the file-based patch pipeline of the prototype.

The following code from kure moved to this repository as the starting point:

• pkg/launcher/ — the prototype pipeline (loader, resolver, patch processor, validator, builder)
• pkg/patch/ — the patch engine (TOML/YAML parsing, JSONPath application, strategic merge, conflict detection)
• cmd/kurel/ and pkg/cmd/kurel/ — the CLI entry point and commands

pkg/launcher/ has since been removed; pkg/patch/ was retained as a standalone library (see §9.1).

3. Core Concept: The Kurel Package

A kurel package is a bundle of OAM specs that can be instantiated with parameters. It represents a reusable, shareable application pattern — think “a web application with ingress, TLS, and external secret injection” as a single distributable unit.

3.1 Package Contents

my-webservice/
├── kurel.yaml          # Package metadata and parameter schema
└── app.yaml            # Application template

kurel.yaml is the package’s public API — it declares the parameters (name, type, default, required) and the package version. app.yaml is a launcher Application document. The package author defines what can be varied; consumers fill in the values.

The Application document uses apiVersion: launcher.gokure.dev/v1alpha1, kind Application. ClusterProfile documents (cluster.yaml) and Package documents (kurel.yaml) use the same API group and version. See docs/oam/design-gvk.md for the full GVK rationale.

3.2 Two Parameter Sets

Every kurel package accepts two distinct parameter sets at instantiation time:

Platform profile (set 1)

Describes how the platform implements each trait. These values are environment-specific, not application-specific. A team managing a cluster defines one platform profile; all applications deployed to that cluster share it.

Examples:

• Which ingress controller is in use (Nginx, Traefik, Gateway API)
• Which certificate authority backs the cert manager (Let’s Encrypt, internal CA)
• Which secret store implementation is active (Vault, AWS Secrets Manager, Azure Key Vault via External Secrets)
• Which GitOps engine is in use (FluxCD, ArgoCD)

Platform profiles express the trait implementation choices made by the platform operator. The OAM spec in the package stays generic (it says “needs ingress”); the platform profile says “ingress on this cluster means a Gateway API HTTPRoute”.

Application values (set 2)

Describes what this specific application instance needs. These are provided per deployment of the package.

Examples:

• Container image and tag
• Replica count
• Resource requests and limits
• Feature flags
• External secret names
• Domain names

3.3 Separation of Concerns

The split between platform profile and application values maps directly onto OAM’s design intent:

• OAM Components define what workloads exist — application developer concern
• OAM Traits define what platform capabilities to attach — platform operator concern
• The trait implementation (how it works) is a platform profile concern, invisible to the application developer

When deploying multiple packages to a cluster, the platform profile is configured once per environment. Each application provides its own values. Platform changes (e.g. switching ingress controllers) update one profile; no individual application spec changes.

4. Architecture

OAM YAML input (app.yaml + cluster.yaml)
        │
        ▼
┌───────────────────┐
│   OAM Parser      │  pkg/oam — parse Application, Component, Trait, Policy
└────────┬──────────┘
         │
         ▼
┌───────────────────┐
│  Handler Registry  │  ComponentHandler + TraitHandler per OAM type
│  + Transformer    │  TransformContext carries ClusterID, Namespace, Policy, Capabilities
└────────┬──────────┘
         │ ApplicationConfig per component
         ▼
┌───────────────────┐
│   kure library    │  github.com/go-kure/kure
│  K8s builders +   │  Deployment, Service, HelmRelease, …
│  GitOps layout    │  pkg/kubernetes + pkg/kubernetes/fluxcd
└────────┬──────────┘
         │
         ▼
  static K8s manifests (GitOps-ready)

Launcher generates static Kubernetes manifests. It does not deploy them. Consumers commit the output to a Git repository and let a GitOps engine (FluxCD) reconcile it into a cluster.

5. Relationship to kure

Launcher is a consumer of kure, not a component of it.

kure remains a standalone library with no dependency on launcher. Launcher imports kure. The dependency is one-directional.

What stays in kure

pkg/stack/generators/kurelpackage/ — historically a kure generator that produced kurel package structure from a kure Application. This package is now being removed from kure (unused by all known consumers; removal tracked in go-kure/kure#539). It does not move to launcher.

What launcher does not use from kure (intentional)

Launcher does not use the following kure packages. This is by design, not an oversight.

What launcher does use from kure (intentional)

6. Comparison with Helm

7. Comparison with KubeVela

KubeVela is the reference OAM runtime. The key architectural difference:

Launcher targets teams committed to a GitOps-first workflow who want OAM semantics without a cluster-side controller.

8. OAM Model

Launcher defines its own OAM types under launcher.gokure.dev/v1alpha1. These are not CRDs — they are static YAML files consumed by kurel build.

Launcher does not use core.oam.dev/v1beta1. That API group belongs to KubeVela’s CRD-based runtime. Launcher is a compile-time tool with its own types.

9. Phase 0 Design Decisions

PR go-kure/launcher#58 closed issues go-kure/launcher#36 (package spec), go-kure/launcher#37 (ClusterProfile), go-kure/launcher#38 (policy interface). These decisions are final.

Decision rule: launcher is a semantically richer Helm alternative. Explicit package API contract and compiler-verified correctness take precedence over YAML validity at rest.

9.1 Later Design Decisions

10. Policy Interface

The Policy interface is launcher’s primary extension point for downstream consumers to enforce environment-specific constraints without modifying launcher’s built-in handlers.

type Policy interface {
    // Enforced limits — nil or empty string means no limit.
    MaxReplicas() *int32
    MaxCPU() string
    MaxMemory() string
    MaxStorageSize() string
    AllowedRegistries() []string
    // Defaults — nil or empty string means leave the OAM value as-is.
    DefaultReplicas() *int32
    DefaultCPURequest() string
    DefaultMemoryRequest() string
    DefaultCPULimit() string
    DefaultMemoryLimit() string
    // Workload-shape defaults — nil or empty string means leave the OAM value as-is.
    DefaultStorageSize() string
    DefaultScalerMinReplicas() *int32
    DefaultScalerMaxReplicas() *int32
    // Security flags — false is the zero value (default-deny).
    AllowHostNetwork() bool
    AllowPrivileged() bool
    AllowHostPID() bool
    AllowHostIPC() bool
    AllowHostPathVolumes() bool
    // Capability constraints — nil means unconstrained.
    AllowedCapabilities() []string
    ForbiddenCapabilities() []string
    RequiredCapabilities() []string
    // Container capability constraints — Linux capabilities on a container's
    // securityContext.capabilities.add, NOT the OAM trait-type strings above.
    // Default-allow, mirroring AllowedRegistries: nil/empty Allowed means no
    // restriction; nil/empty Forbidden means no forbids; forbidden wins on overlap.
    AllowedContainerCapabilities() []string
    ForbiddenContainerCapabilities() []string
}

NoopPolicy is the default when no policy document is supplied: no enforced limits, no defaults applied, security-sensitive boolean flags default-deny (false) — except the two container-capability accessors, which are default-allow (nil means unconstrained, go-kure/launcher#305). Downstream consumers implement Policy (typically via their own EnvironmentPolicy type) to add enforcement. See docs/oam/options-policy-interface.md for the full design rationale.

12. What Launcher Does NOT Do

13. Current Status and Roadmap

Phase 0 (complete): Extraction, design, and housekeeping

• Move prototype code from kure — done
• Establish module structure and CI — done
• Design OAM-native application model (GVK, ClusterProfile, Policy, package spec) — done (go-kure/launcher#36, go-kure/launcher#37, go-kure/launcher#38)
• Clean up prototype pipeline and align CLI with OAM design — done (go-kure/launcher#40, go-kure/launcher#41, go-kure/launcher#42)

Phase 1: OAM Core (go-kure/launcher#31)

• pkg/oam: types, parser, validator (go-kure/launcher#43)
• pkg/oam: handler interfaces (ComponentHandler, TraitHandler, CapabilityAware) (go-kure/launcher#44)
• pkg/oam: ClusterProfile and CapabilityBinding types (go-kure/launcher#45)
• pkg/oam: Policy interface, Enforceable interface, NoopPolicy (go-kure/launcher#46)
• pkg/oam: OAM runtime skeleton (Transformer, handler registry, TransformContext) (go-kure/launcher#47)
• pkg/oam: transform pipeline (capability wiring, policy application) (go-kure/launcher#53)
• Fixture parity and regression coverage (go-kure/launcher#54)

Phase 1b / Vertical Slice (complete): First end-to-end kurel build (go-kure/launcher#56)

• One component + one trait → working manifest output
• Validates the OAM parser → handler → kure pipeline end-to-end

Phase 2: Built-in handlers (go-kure/launcher#32)

• Component handlers: webservice, worker, deployment, postgresql, cronjob, job, helmrelease, helmtemplate, daemonset, statefulset, service (go-kure/launcher#48, go-kure/launcher#343, go-kure/launcher#344, go-kure/launcher#411, go-kure/launcher#327, go-kure/launcher#348)
• Trait handlers — workload set: expose, certificate, external-secret, pvc, scaler (go-kure/launcher#49)
• Trait handlers — network/infra set: ingress, httproute, configmap, networkpolicy, cilium-networkpolicy, volsync (go-kure/launcher#50)
• Generic passthrough component — emits arbitrary CRDs / non-standard objects with no per-type Go handler (go-kure/launcher#105)
• Manifest-source components: crd, manifests — emit CRDs / arbitrary manifests from inline or http(s) URL sources, with scope-aware namespace stamping (classifier in kure pkg/manifest); for content authored as YAML rather than as typed component properties
• oci source component — emits an OCIRepository source CR (URL+version dedup, flux-namespace placement) plus a per-component Flux Kustomization; for content already published as an OCI artifact, reconciled by Flux
• Kind-named Flux source components: helmrepository, ocirepository, gitrepository, bucket — each a strict 1:1 projection of its source-controller spec, emitting exactly one source CR (no dedup, flux-namespace placement, fetch host constrained by the policy registry allowlist) (go-kure/launcher#347)
• Kind-named helmchart component — the Flux HelmChart source, a strict 1:1 projection of HelmChartSpec emitting exactly one CR in the Flux namespace; it reuses the name of the removed helmchart composite, whose top-level keys get a hint pointing to helm (go-kure/launcher#351)
• Kind components for the objects the workload kinds generate for themselves: serviceaccount, persistentvolumeclaim, configmap. Each emits exactly one object named after the component. A pvc volume’s claimName mounts an existing claim without generating one. webservice and worker emit their ServiceAccount as a serviceaccount sibling member and their described claims as synthesized pvc traits, with byte-identical output; the five pod kinds (deployment, statefulset, daemonset, cronjob, job) generate no ServiceAccount and no claim, and their pvc volumes require claimName (go-kure/launcher#702)
• Role-named helm component — a component-position lowering rule onto helmrelease (plus a generated helmrepository/ocirepository, shared per URL within an application and applied with the application bundle, ahead of its ordered groups) or helmtemplate; the successor to the removed helmchart composite (go-kure/launcher#349, go-kure/launcher#350)

Phase 3 (complete): CLI integration (go-kure/launcher#33)

• kurel build — OAM mode (app.yaml + –profile cluster.yaml → manifests) (go-kure/launcher#51)

Phase 4: Downstream integration (go-kure/launcher#34) — deferred

• a downstream runtime becomes a launcher consumer; EnvironmentPolicy, handler migration

Phase 5: OCI distribution (go-kure/launcher#35) — gate met, not yet started

• OCI-based package publishing and pulling
• Package catalog as OCI index (go-kure/launcher#16)

14. Open Questions

1. Conditional inclusion syntax — No optional sections in Phase 1. Package authors publish always-on packages; separate packages cover distinct deployment variants. Boolean on/off gates and multi-instance support are Phase 2 (issue go-kure/launcher#39).

2. Generic/raw YAML escape hatch — Implemented as the passthrough component (go-kure/launcher#105): it emits an arbitrary Kubernetes object declared inline under object:, with a clusterScoped flag for cluster-scoped resources, covering cases outside the built-in handler set. Config-driven custom traits and template/plugin rendering remain future work (go-kure/launcher#102).

3. Package distribution — How kurel packages are published, versioned, and referenced by consumers. kurel build runs today against a standard local layout without extra flags (Phase 3, complete); OCI-based publishing and pulling is Phase 5, gate met but not yet started.