# OAM Spec v0.2.2 Working Draft

Hi all, this is the issue tracker to finalize the design of OAM spec v0.2.2. It reflects the high level ideas of the existing working draft in master branch with considerations on backward compatibility in existing releases.

> As a working draft, the below design is open for revise, but we should try best to keep the changes minimal.

## 1. ComponentDefinition

> Purpose: refactor `Component` in v0.2.1 and `ComponentSchematic` of v1alpha1 to combine all the schematic primitives in one object, w/o any instance values.

> Target user: component provider, software distributor

apiVersion: core.oam.dev/v1alpha3
kind: ComponentDefinition
metadata:
  name: webservice
  namespace: foo # install this component in namespace foo
spec:
  workload: # workload type descriptor
    type: core.oam.dev.containerizedworkload # ref to a WorkloadDefinition via name
    definition: # mutually exclusive to workload.type, a embedded WorkloadDefinition
      apiVersion: core.oam.dev/v1alpha2
      kind: ContainerizedWorkload
  schematic:
    kube: # this section is same with v0.2.1 component spec (i.e. raw k8s resource template)
      template:
        apiVersion: core.oam.dev/v1alpha2
        kind: ContainerizedWorkload
        spec:
        ...
          containers:
          - name: my-cool-workload
            image: example/very-cool-workload:0.1.2@sha256:verytrustworthyhash
            resources:
              cpu:
                required: 1.0
              memory:
                required: 100MB
            cmd:
            - "bash lscpu"
      parameters: 
      - name: image
        required: true
        fieldPaths: 
        - "spec.containers[0].image"
      - name: cmd
        required: true
        fieldPaths:
        - "spec.containers[0].cmd"
    cue:
      # cue template and parameters 
    helm:
      # a helm chart
    arm:
      # Azure ARM template & parameter schema
status:
  parameters: # a generated json schema of parameters, equivalent to spec.parameters but friendly to k8s impl

> The implementation will auto generate the jsonschema of module parameters and patch it to the status of `ComponentDefinition`.

## 2. WorkloadDefinition

> Purpose: equivalent to `WorkloadDefinition` in v0.2.1, a missing concept in v1alpha1

> Target user: this is an optional system level object, the main use case is for custom workload type discovering.

apiVersion: core.oam.dev/v1alpha2
kind: WorkloadDefinition
metadata:
  name: core.oam.dev.containerizedworkload
spec:
  definitionRef: # crd of this workload
    apiVersion: core.oam.dev/v1alpha2
    kind: ContainerizedWorkload
  childResources:
    - apiVersion: apps/v1
      kind: Deployment

## 3. Application

> Purpose: equivalent to `ApplicationConfiguration` in v0.2.1 and v1alpha1

> Target user: app dev, app ops, end users

apiVersion: core.oam.dev/v1alpha2
kind: Application
metadata:
  name: application-sample
spec:
  components:
    - name: myweb
      type: foo/webservice # ref to ComponentDefinition, optionally, in namespace foo
      settings: # workload settings - consistency
        image: "busybox"
        cmd:
        - sleep
        - "1000"
      traits: # assume traits are in oam system namespace for now
        - name: scaler
          properties:
            replicas: 10
        - name: sidecar
          properties:
            name: "sidecar-test"
            image: "nginx"

## 4. TraitDefinition

> Purpose: equivalent to `TraitDefinition` in v0.2.1 and `Trait` of v1alpha1

> Target user: infra ops, platform builders, traits are platform provided capabilities, end users should not modify traits - they only use them

apiVersion: core.oam.dev/v1alpha2
kind: TraitDefinition
metadata:
  name: scaler
spec:
  appliesToWorkloads:
    - core.oam.dev.containerizedworkload # arbitrary workload definition
    # support k8s label selector in the future
  definitionRef:
    apiVersion: xxx
    kind: xxx
  schematic:
    # seems we don't need kube type for trait, definitionRef is enough
    cue:
      # cue template and parameters
    helm:
      # a helm chart
    ... # could have more module types in the future
status:
  parameters: # a optional generated json schema of parameters, equivalent to spec.parameters but friendly to k8s impl

## 5. ApplicationScope

No change with spec v0.2.1

## Open Questions

### 1. Behavior of traits for revisioned components.

Traits are attached to component __instances__, and those instances are revisioned. Should we replica the traits then (e.g. ingress vs. {ingress-v1, ingress-v2})?

In previous code, as a workaround, we tagged `TraitDefinition` as `revisionEnabled` to control this behavior, though recently we fallback to assume ALL traits are replicated but have to leave `rollout` to a seperate field (since it is across-revisions).