Kurel Packages

Design: Kurel Package Spec

Status: Final | Issue: go-kure/launcher#36

1. Purpose

A kurel package is a distributable, reusable OAM application pattern. It bundles:

• an OAM Application document (app.yaml) describing what workloads to run and what platform capabilities they need
• a package metadata file (kurel.yaml) with identity and parameter declarations
• optionally, example value files for common deployment scenarios

Packages are designed to be shared: a team defines a webservice-with-ingress package once and any project instantiates it by supplying their image, domain, and values.

2. Package Directory Layout

my-app/
├── kurel.yaml        # package identity and parameter schema
├── app.yaml          # launcher Application (launcher.gokure.dev/v1alpha1)
└── examples/
    ├── production.yaml   # example values for a production deployment
    └── staging.yaml      # example values for a staging deployment

The OAM Application format replaces the prototype’s parameters.yaml + resources/ + patches/ layout. No coexistence or backward-compatible bridging is required.

3. kurel.yaml

kurel.yaml declares the package identity and the parameter schema.

apiVersion: launcher.gokure.dev/v1alpha1
kind: Package
metadata:
  name: webservice        # package identifier
  version: "1.0.0"        # semver
  description: "A stateless web service with ingress, TLS, and optional autoscaling."
  # Future: home, keywords, maintainers (informational only)
spec:
  parameters:
  - name: image
    type: string
    required: true
    description: "Container image with tag, e.g. registry/app:v1.2.3"
  - name: domain
    type: string
    required: true
    description: "Primary hostname, e.g. app.example.com"
  - name: replicas
    type: integer
    required: false
    default: 1

4. app.yaml — OAM Application

app.yaml is a launcher Application document (launcher.gokure.dev/v1alpha1, kind Application). It contains ${var} parameter placeholders that the resolver substitutes using the values supplied at build time. The component and trait types must match the handler registry that the runtime is configured with. See docs/oam/design-gvk.md for the GVK rationale and docs/oam/options-param-syntax.md for the parameter syntax spec.

4.1 Basic structure

apiVersion: launcher.gokure.dev/v1alpha1
kind: Application
metadata:
  name: my-app
spec:
  components:
  - name: web
    type: webservice        # must match a registered ComponentHandler
    properties:
      image: myregistry/myapp:1.0.0
      port: 8080
      replicas: 1
    traits:
    - type: expose          # must match a registered TraitHandler
      properties:
        rules:
        - host: my-app.example.com
          paths:
          - path: /
            port: 8080

4.2 Supported component types (Phase 1)

Ported from the downstream runtime. Each type maps to a ComponentHandler implementation in pkg/oam/builtin/:

4.3 Supported trait types (Phase 1)

Each type maps to a TraitHandler in pkg/oam/builtin/traits/ — expose to a TraitLoweringRule there. Rows marked launcher-native were not ported from the downstream runtime:

pkg/oam/builtin/traits/README.md is the authoritative trait catalog; its tables list each trait’s key properties, not every accepted field. The one downstream trait with no launcher counterpart is backup, which depends on the downstream delivery pipeline and has no meaning in a static manifest build. fluxcd-patches and fluxcd-postbuild configure the Flux Kustomization that delivers a bundle and are not built in either (go-kure/launcher#781): a consumer that delivers through Flux registers its own handlers for them.

4.4 OAM policies

Each spec.policies entry is dispatched by type to a PolicyHandler in pkg/oam/builtin/policies/; a type with no handler fails the build with no handler for policy type. A policy shapes how the application is grouped and ordered, not which objects it emits:

app-dependency (ordering one application after others) is not built in: kurel build builds a single application and has nothing to order it against. A caller that orchestrates several applications registers its own handler for it. reconciliation and health-checks are not built in either: they configure delivery, which launcher leaves to the consumer that delivers the application (go-kure/launcher#781; see docs/delivery-scope.md). Such a consumer registers its own handler and returns what it read through PolicyResult.Extensions.

spec:
  # ...
  policies:
  - name: deploy-order
    type: dependency
    properties:
      rules:
      - component: web
        dependsOn: [db]

These are distinct from the Policy interface (options-policy-interface.md), the environment constraints a caller passes in the transform context; kurel build uses NoopPolicy for that.

5. Two-Parameter-Set Model

Every kurel build receives exactly two parameter sets:

Set 1 — Platform profile (--profile cluster.yaml)

Describes how the platform implements each trait. This is an environment-level input, supplied by the platform operator and shared across all applications on a cluster. Represented as a ClusterProfile document. See docs/oam/design-cluster-profile.md.

Set 2 — Application values

Describes what this specific deployment needs: image, replica count, domain names, etc. This is a per-deployment input, supplied by the application team at build time.

The two sets are merged at different stages:

• Platform profile rendering is merged into trait properties before handler invocation (capability resolution, see ClusterProfile design)
• Application values are merged into component and trait properties (${var} placeholder substitution — see §6)

Separation of concerns

┌─────────────────────────────────────────────────────────────────┐
│  Application team provides:                                     │
│  - app.yaml (launcher Application — what to run, what capabilities)  │
│  - values  (image, replicas, domains — per deployment)          │
└─────────────────────┬───────────────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────────────┐
│  kurel build                                                    │
│  1. Resolve application values into OAM Application             │
│  2. Load ClusterProfile (platform profile)                         │
│  3. For each trait: merge capability rendering into properties     │
│  4. Dispatch to component and trait handlers                    │
│  5. Output: static Kubernetes manifests                         │
└─────────────────────┬───────────────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────────────┐
│  Platform operator provides:                                    │
│  - cluster.yaml (ClusterProfile — how traits are implemented)   │
└─────────────────────────────────────────────────────────────────┘

6. Parameter Syntax

Application values are expressed as ${name} placeholders in app.yaml. The resolver substitutes all placeholders using the values supplied at build time before the Application is parsed or dispatched to handlers. For the full design rationale see docs/oam/options-param-syntax.md.

6.1 Parameter declarations in kurel.yaml

Each parameter has a name, type, required flag, optional default, and optional description.

Schema vocabulary. Internally a parameter is ParameterDecl = name plus the shared PropertySchema vocabulary (the same type used by handler properties and capability rendering). Parameters remain an ordered list — a default may reference only earlier parameters — and are restricted to the flat subset: the rich PropertySchema fields (enum, nested properties, items, additionalProperties) are rejected at decode time. Unifying the type does not change the accepted wire format.

spec:
  parameters:
  - name: image
    type: string
    required: true
    description: "Container image with tag, e.g. registry/app:v1.2.3"
  - name: replicas
    type: integer
    required: false
    default: 1
  - name: domain
    type: string
    required: true
  - name: tlsSecret
    type: string
    required: false
    default: "${name}-tls"   # may reference other parameters

Supported types: string, integer, boolean, array, object. An array or object parameter carries a YAML list or map and is substituted as a whole node (6.3). Its default, if any, must be a list or map; a string default is refused, not parsed as YAML.

6.2 Placeholder syntax in app.yaml

spec:
  components:
  - name: web
    type: webservice
    properties:
      image: "${image}"          # scalar substitution — resolves to string
      replicas: ${replicas}      # scalar substitution — resolves to integer
    traits:
    - type: expose
      properties:
        rules:
        - host: "${domain}"
    - type: certificate
      properties:
        secretName: "${tlsSecret}"
        dnsNames:
        - "${domain}"

6.3 Resolver behaviour

Scalar substitution — when ${name} is the entire value of a YAML field, the resolver replaces it with the typed value from the parameter declaration:

• image: "${image}" → image: "myregistry/app:v1.2.3" (string)
• replicas: ${replicas} → replicas: 3 (integer, not string "3")

Node substitution — for an array or object parameter, a whole-value ${name} is replaced by the value’s YAML list or map:

• env: ${env} → env: [{name: LOG_LEVEL, value: info}]
• Only the shape (list or map) is checked against the parameter, since a parameter declares no items or properties; the substituted value is then validated by the consuming component’s or trait’s schema like any authored property
• The replacement is not scanned again: a ${…} inside a supplied value stays literal
• Embedding an array/object placeholder inside a larger string is an error, in the application template and in another parameter’s string default alike; an anchor on the placeholder stays on the substituted node

Inline string embedding — when ${name} is embedded inside a larger string value:

• secretName: "${name}-tls" → secretName: "webservice-tls" (always a string)

6.4 Supplying values at build time

kurel build . --profile cluster.yaml --values values.yaml

# --set flags — scalars only; supply array/object parameters with --values
kurel build . --profile cluster.yaml \
    --set image=myregistry/app:v1.2.3 \
    --set replicas=3 \
    --set domain=app.example.com

# values.yaml
image: myregistry/app:v1.2.3
replicas: 3
domain: app.example.com

6.5 Validation

• Missing required parameter → build error naming the parameter before any resolution
• Optional parameter with no value → default value used
• default may itself contain ${name} references to other parameters; these are resolved in declaration order
• default values are type-checked at ParsePackage time; a string default that is not parseable as the declared type (e.g. default: foo for type: integer) is rejected immediately

7. Build Invocation

kurel build <package-dir> \
    --profile cluster.yaml \
    [--values values.yaml | --set key=value]

Output is static Kubernetes manifests on stdout (YAML, multi-document). Pipe into kubectl apply, a GitOps repo, or a CI artifact store.

The --profile flag is required. Without a profile, capability-aware traits will fail with ErrMissingCapability.