How to Model and Expose Cloud Services with OAM: A Practical Guide

Open Application Model (OAM) Overview

OAM is a lightweight, cloud‑native model for describing, operating, and delivering applications on Kubernetes. It enables service providers to expose capabilities in a standard way and allows platform teams to consume those services uniformly.

1. Classify OAM Types

Each service must be mapped to one of three OAM categories (Workload, Trait, Scope). This classification clarifies the purpose of the service on the platform.

2. Write OAM Definitions

After classification, create an OAM definition that consists of generic metadata and a custom API description. JSON Schema is used to describe the API because it is open and widely supported.

Workload example (RDS)

apiVersion: oam.dev/v1alpha1
kind: WorkloadType
metadata:
  name: rds
spec:
  group: alibaba.io/v1
  names: [RDS]
  settings: |
    {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "type": "object",
      "required": ["storageType"],
      "properties": {
        "storageType": {
          "type": "string",
          "description": "The type of storage for RDS instance"
        }
      }
    }

Trait example (ManualScaler)

apiVersion: core.oam.dev/v1alpha1
kind: Trait
metadata:
  name: ManualScaler
  annotations:
    version: v1.0.0
    description: "Allow operators to manually scale a workload with multiple replicas."
spec:
  appliesTo:
    - core.oam.dev/v1alpha1.Server
    - core.oam.dev/v1alpha1.Worker
    - core.oam.dev/v1alpha1.Task
  properties: |
    {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "type": "object",
      "required": ["replicaCount"],
      "properties": {
        "replicaCount": {
          "type": "integer",
          "description": "Target number of replicas to scale the component to.",
          "minimum": 0
        }
      }
    }

3. Implement the OAM Operator

To make the OAM spec executable, implement a Kubernetes Operator. Alibaba Cloud’s open‑source oam-go-sdk provides helpers for building the API and the operator.

4. Service Exposure and Consumption

OAM standardizes how a service publishes its connection information and how a consumer retrieves it. Typical patterns include:

Service Broker writes service details into a CRD status; a workflow reads the status and injects the data into application environment variables.

ROS outputs service details as template parameters for downstream applications.

Crossplane defines a unified MySQL resource and writes connection data into a Secret that the consumer mounts.

5. Solution Approach

The OAM runtime processes an AppConfig and performs the following steps:

Detect that a consumer Component needs a provider Component and schedule creation order.

Create the provider Workload Component, write its connection information into a Secret whose name is defined by the expose field.

Create the consumer Component and inject the Secret either as environment variables or as files, according to the consume declaration.

6. End‑to‑End Example

Define a CloudSQL component (provider) with an expose field that creates a Secret named mysql-connection:

apiVersion: oam.dev/v1alpha1
kind: Component
metadata:
  name: mysql
spec:
  workloadType: database.cloud.io/v1beta1.CloudSQL
  expose:
    name: mysql-connection
  # other parameters omitted

After the MySQL Workload is created, the runtime writes the connection details into the mysql-connection Secret.

A web application component can consume the secret:

apiVersion: oam.dev/v1alpha1
kind: Component
metadata:
  name: web
spec:
  workloadType: Server
  consume:
    - name: mysql-connection
      as: env  # can also be injected as a file

Conclusion

This guide shows how to classify a service, write its OAM Workload or Trait definition using JSON Schema, implement an OAM operator with oam-go-sdk, and use the OAM runtime to expose service connection information via Secrets and consume it in downstream components. Although OAM is still evolving, the described workflow provides a concrete path for integrating cloud services on Kubernetes.