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
ComponentDefinitionthat 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
TraitDefinitionthat 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
-
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 -
Look at the bundled component types:
vela components # webservice, worker, task, cron-task, daemon, raw, k8s-objects, helmwebserviceis the most common — a Deployment + Service.helmlets you reference a Helm chart as a Component.k8s-objectslets you embed arbitrary Kubernetes YAML. -
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.localThis single resource creates: a Deployment with 3 replicas, a Service, an Ingress for
payments-api.acme.examplerouting to port 8080, and env vars on the Deployment’s pods. -
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 } -
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"] } -
Backstage integration. If you run Backstage (see /en/knowledge-base/backstage-software-catalog/), Components in the catalog can reference an
Applicationresource as their workload, with the KubeVela UI plugin showing rollout status. -
Decommission via
kubectl delete application. KubeVela tracks owner references; deleting the Application cleans up everything it produced. Don’tkubectl delete deploymentmanually — 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
ComponentDefinitionandTraitDefinitionas 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: rawortype: 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.