What’s New in OAM v1alpha2? Key Changes and Migration Guide

Background

The OAM (Open Application Model) specification has been iterated for nearly three months and the v1alpha2 version is now released. It retains platform‑agnostic principles while becoming significantly more Kubernetes‑friendly, balancing standardization with extensibility and improving CRD support.

1. Terminology

CRD (Custom Resource Definition) : In OAM it refers to a generic custom resource definition that maps directly to Kubernetes CRDs, or to a similar construct in non‑Kubernetes implementations.

CR (Custom Resource) : An instance of a CRD, representing a concrete resource description.

2. Reference Model – Workload, Trait, and Scope Definitions

v1alpha2 replaces the previous schema‑centric approach with a reference model. WorkloadDefinition, TraitDefinition, and ScopeDefinition now reference existing CRDs by name, allowing direct reuse of Kubernetes CRDs.

apiVersion: core.oam.dev/v1alpha2
kind: WorkloadDefinition
metadata:
  name: containerisedworkload.core.oam.dev
spec:
  definitionRef:
    name: containerisedworkload.core.oam.dev

apiVersion: core.oam.dev/v1alpha2
kind: TraitDefinition
metadata:
  name: manualscalertrait.core.oam.dev
spec:
  appliesToWorkloads:
    - containerizedworkload.core.oam.dev
  definitionRef:
    name: manualscalertrait.core.oam.dev

apiVersion: core.oam.dev/v1alpha2
kind: ScopeDefinition
metadata:
  name: networkscope.core.oam.dev
spec:
  allowComponentOverlap: true
  definitionRef:
    name: networkscope.core.oam.dev

3. Embedding Full CRs in Component and Trait Instances

Instead of extracting only the spec fields, the new model embeds the complete CR under workload or trait. This enables seamless integration with native Kubernetes resources such as Deployments.

apiVersion: core.oam.dev/v1alpha2
kind: Component
metadata:
  name: example-server
spec:
  workload:
    apiVersion: core.oam.dev/v1alpha2
    kind: Server
    spec:
      osType: linux
      containers:
        - name: my-cool-server
          image:
            name: example/very-cool-server:1.0.0
          ports:
            - name: http
              value: 8080
          env:
            - name: CACHE_SECRET

4. Parameter Injection via jsonPath

Parameter values are now injected using jsonPath expressions, replacing the previous fromParam function. This keeps ApplicationConfiguration static while allowing developers to define parameters and operators to override them.

apiVersion: core.oam.dev/v1alpha2
kind: Component
metadata:
  name: example-server
spec:
  parameters:
    - name: instanceName
      required: true
      fieldPaths:
        - ".metadata.name"
    - name: cacheSecret
      required: true
      fieldPaths:
        - ".workload.spec.containers[0].env[0].value"

5. Renaming ComponentSchematic to Component

The former ComponentSchematic concept is renamed to Component, clarifying that it represents an instance of a Workload. All syntax definitions now reside in the referenced WorkloadDefinition.

6. Scope Creation Shifted to ScopeDefinition

Scopes are no longer created via ApplicationConfiguration; instead, a dedicated Scope CR is created from a ScopeDefinition. ApplicationConfiguration now references existing Scope instances.

apiVersion: core.oam.dev/v1alpha2
kind: NetworkScope
metadata:
  name: example-vpc-network
  labels:
    region: us-west
    environment: production
spec:
  networkId: cool-vpc-network
  subnetIds:
    - cool-subnetwork
    - cooler-subnetwork
    - coolest-subnetwork
  internetGatewayType: nat

apiVersion: core.oam.dev/v1alpha2
kind: ApplicationConfiguration
metadata:
  name: custom-single-app
spec:
  components:
    - componentName: frontend
      scopes:
        - scopeRef:
            apiVersion: core.oam.dev/v1alpha2
            kind: NetworkScope
            name: my-vpc-network
    - componentName: backend
      scopes:
        - scopeRef:
            apiVersion: core.oam.dev/v1alpha2
            kind: NetworkScope
            name: my-vpc-network

7. Removal of Variables and Dynamic Functions

The variables list and the fromVariable() function have been removed, as their functionality can be achieved with existing templating tools (e.g., Helm, Kustomize).

8. Consolidating Core Workloads into ContainerizedWorkload

All six original core Workload types are unified under a single ContainerizedWorkload definition, simplifying the model while allowing trait‑specific constraints.

apiVersion: core.oam.dev/v1alpha2
kind: WorkloadDefinition
metadata:
  name: containerizedworkloads.core.oam.dev
spec:
  definitionRef:
    name: containerizedworkloads.core.oam.dev

apiVersion: core.oam.dev/v1alpha2
kind: Component
metadata:
  name: frontend
spec:
  workload:
    apiVersion: core.oam.dev/v1alpha2
    kind: ContainerizedWorkload
    spec:
      osType: linux
      containers:
        - name: web
          image: example/charybdis-single:latest@@sha256:verytrustworthyhash
          resources:
            cpu:
              required: 1.0
            memory:
              required: 100MB
          env:
            - name: MESSAGE
              value: default
  parameters:
    - name: message
      description: The message to display in the web app.
      required: true
      type: string
      fieldPaths:
        - ".spec.containers[0].env[0].value"

Next Steps

Support inter‑component parameter passing and dependency workflows.

Introduce a Policy mechanism so developers can request specific traits in a Component.

Add versioning to Components and define OAM‑based application release strategies.

The OAM specification continues to evolve, and community contributions are welcomed to shape the future of cloud‑native application delivery.