Skip to content

OAM — Open Application Model overview

OAM separates application definition from infrastructure concerns. Components, Traits, Workflows, and KubeVela as the reference runtime — how it fits into a platform.

The Open Application Model is a spec for describing an application without baking in the infrastructure that runs it. Developers describe what the application is (the Components) and what behavior it needs (the Traits, like autoscaling or ingress); platform operators describe how those Components and Traits map to concrete Kubernetes (or other) resources. The reference implementation is KubeVela, an open-source controller that converts OAM Application resources into the underlying manifests. This article covers the model, where it differs from “just use Helm,” and the operating shape we run for clients who adopt it.

How to verify

vela version
vela components
vela traits
vela ls -A
vela status payments-api
kubectl get application -A
kubectl get applicationrevision -A

vela components and vela traits list the platform’s vocabulary — the Component and Trait definitions that developers can use in their Application. If a developer asks for type: webservice and it doesn’t exist, the platform team hasn’t defined it; the application fails admission with a clear error.

What’s happening

OAM separates three concerns:

  • Components. What the application is: a web service, a worker, a job. A Component has a name, a type, and properties (image, ports, env). The shape of a Component is defined by a platform-side ComponentDefinition that says “when you say type=webservice, I’ll create a Deployment with this template.”
  • Traits. Behaviors applied to a Component: scaling, ingress, sidecars, image-pull-secrets, persistent storage. Each Trait is defined by a platform-side TraitDefinition that says “when you attach trait=ingress, here’s the Ingress resource I produce.”
  • Policies and Workflow. How and where the application gets deployed: target clusters, rollout strategy, approval gates, sequential or parallel steps.

KubeVela is the reference runtime. It runs as a Kubernetes operator that watches Application CRDs, expands them through the registered ComponentDefinitions and TraitDefinitions (which are written in CUE — a configuration language), and produces the underlying Kubernetes manifests. The split matters: developers don’t see CUE, don’t see the rendered manifests; they see a small high-level API. The platform team owns the CUE and the resulting shape.

This is the same separation Score (see /en/knowledge-base/score-dev-workload-spec/) makes, with two material differences: (1) OAM has Traits as first-class — a Component knows nothing about ingress, scaling, or sidecars until a Trait attaches them — whereas Score wires everything in the spec; (2) OAM ships with a workflow engine for multi-step deploys, whereas Score is just spec.

The procedure

  1. Install KubeVela. Helm chart:

    helm repo add kubevela https://kubevela.github.io/charts
    helm install kubevela kubevela/vela-core -n vela-system --create-namespace
    vela addon enable velaux
  2. Look at the bundled component types:

    vela components
    # webservice, worker, task, cron-task, daemon, raw, k8s-objects, helm

    webservice is the most common — a Deployment + Service. helm lets you reference a Helm chart as a Component. k8s-objects lets you embed arbitrary Kubernetes YAML.

  3. Write an Application:

    apiVersion: core.oam.dev/v1beta1
    kind: Application
    metadata:
      name: payments-api
      namespace: payments
    spec:
      components:
        - name: api
          type: webservice
          properties:
            image: acme/payments-api:1.42.3
            port: 8080
            cpu: "0.5"
            memory: "512Mi"
          traits:
            - type: scaler
              properties: { replicas: 3 }
            - type: gateway
              properties:
                domain: payments-api.acme.example
                http: { "/": 8080 }
            - type: env
              properties:
                env:
                  LOG_LEVEL: info
                  DB_HOST: payments-pg.databases.svc.cluster.local

    This single resource creates: a Deployment with 3 replicas, a Service, an Ingress for payments-api.acme.example routing to port 8080, and env vars on the Deployment’s pods.

  4. Custom ComponentDefinition. When the bundled types don’t fit, the platform team writes a CUE-defined Component:

    apiVersion: core.oam.dev/v1beta1
    kind: ComponentDefinition
    metadata:
      name: stateful-api
      namespace: vela-system
    spec:
      workload:
        definition:
          apiVersion: apps/v1
          kind: StatefulSet
      schematic:
        cue:
          template: |
            output: {
              apiVersion: "apps/v1"
              kind:       "StatefulSet"
              spec: {
                serviceName: parameter.name
                replicas:    parameter.replicas
                selector: matchLabels: app: parameter.name
                template: {
                  metadata: labels: app: parameter.name
                  spec: containers: [{
                    name:  "main"
                    image: parameter.image
                    ports: [{containerPort: parameter.port}]
                  }]
                }
              }
            }
            parameter: {
              name: string
              image: string
              port: int | *8080
              replicas: int | *1
            }
  5. Multi-cluster rollout. OAM’s workflow lets you stage:

    spec:
      components: [...]
      policies:
        - name: target-prod
          type: topology
          properties:
            clusters: ["prod-us-east-1", "prod-eu-west-1"]
        - name: canary
          type: deploy
          properties: { auto: false }
      workflow:
        steps:
          - name: deploy-staging
            type: deploy
            properties: { policies: ["target-staging"] }
          - name: manual-approval
            type: suspend
          - name: deploy-prod
            type: deploy
            properties: { policies: ["target-prod"] }
  6. Backstage integration. If you run Backstage (see /en/knowledge-base/backstage-software-catalog/), Components in the catalog can reference an Application resource as their workload, with the KubeVela UI plugin showing rollout status.

  7. Decommission via kubectl delete application. KubeVela tracks owner references; deleting the Application cleans up everything it produced. Don’t kubectl delete deployment manually — you’ll just confuse the reconciler.

Operational notes

  • CUE is the learning curve. Component and Trait definitions are written in CUE; if your platform team doesn’t have CUE knowledge, expect a ramp.
  • Definitions are platform-owned, versioned. Treat ComponentDefinition and TraitDefinition as platform API surface — break-the-glass changes require all dependent Applications to be re-evaluated.
  • ApplicationRevision history. Every change to an Application creates a revision; KubeVela can roll back to any prior revision. Useful for “what did this app look like a month ago.”
  • vela addons. KubeVela ships addons for cert-manager, FluxCD integration, observability stack — useful as platform-level Components, not workload-level.
  • The reconciliation cadence is per-Application. Drift correction happens; if someone kubectl edits a Deployment that KubeVela created, the next reconciliation reverts it.

Common pitfalls

  • Conflating Components with Traits. “Should ingress be in my Component definition or as a Trait?” Trait is the right answer — it’s a behavior layered on, not part of the workload identity.
  • Custom Definition that mutates other resources. A TraitDefinition that touches resources owned by another controller fights with that controller. Scope Traits to resources the workload owns.
  • No platform investment. Without good Component/Trait definitions, developers fall back to type: raw or type: k8s-objects, which is just embedding YAML — the abstraction provides no value.
  • Multi-cluster workflow without RBAC. A workflow that deploys to “all prod clusters” needs KubeVela to have credentials to all of them. Service account / kubeconfig hygiene is essential.
  • Application revision sprawl. Every minor change creates a revision; on a high-churn app, you accumulate hundreds of revisions in etcd. Tune retention.

We deploy KubeVela for clients who want a clearer split between “what the app is” and “how the platform runs it” than Helm gives, and who have the platform-team capacity to invest in Component and Trait definitions. The shape lives inside /en/services/managed-operations/ — we own the definitions and the workflow engine, the dev teams own their Application manifests. For organizations earlier in the developer-portal journey, Score at /en/knowledge-base/score-dev-workload-spec/ is a lower-investment cousin worth evaluating first.