# OAM Control Plane (Ideal Design)

## ComponentSchematic & Trait

apiVersion: core.oam.dev/v1alpha3
kind: ComponentSchematic
metadata:
  name: WebService
  annotations:
    version: v1.0.0 # only one version can be installed in the system
    description: "A simple web service"
spec:
  definitionRef:
    apiVersion: apps/v1
    kind: Deployment
  template:
    # CUE template and parameters ...
---
apiVersion: core.oam.dev/v1alpha3
kind: Trait
metadata:
  name: Ingress
  annotations:
    version: v1.0.0 # only one version can be installed in the system
    description: "A Nginx ingress to access the app"
spec:
  definitionRef:
    apiVersion: networking/v1
    kind: Ingress
  template:
    # CUE template and parameters ...

Tips:
- `ComponentSchematic` is equivalent to `WorkloadDefinition` in v1alpha2.
- `Trait` is equivalent to `TraitDefinition` in v1alpha2.
- Both `ComponentSchematic` and `Trait`:
- are a schema objects which define abstraction template and configurable parameters.
- are shareable across teams, orgs and platforms.
- are defined and maintained by platform team.

## ApplicationConfiguration

apiVersion: core.oam.dev/v1alpha3
kind: ApplicationConfiguration
metadata:
  name: custom-single-app
  annotations:
    description: "Customized version of single-app"
spec:
  components:
    - type: WebService
      name: frontend
      settings:
        containers:
          - name: web
            image:
              name: example/charybdis-single:latest
      traits:
        - kind: Ingress
          properties:
            host: "www.example.com"
            path: "/"
      scopes:
        - my-vpc-network

Tips:
- `ApplicationConfiguration` is the mutable presentation of the whole app. The system will generate immutable k8s resources on every change of this object.
- Platform team is expected to build upper layer UI such as Appfile and Dashboard to generate `ApplicationConfiguration`.

### Revision

Change on `ApplicationConfiguration` will generate a new revision like so:

$ kubectl get controllerrevision
custom-single-app-v1
custom-single-app-v2

Every revision will render **all** corresponding k8s resources of the whole app under this revision. The exception is when `ComponentSchematic` claims `revision: false`.

Exception 1: workload reference only

apiVersion: core.oam.dev/v1alpha3
kind: ApplicationConfiguration
metadata:
  name: custom-single-app
  annotations:
    description: "Customized version of single-app"
spec:
  components:
    - type: WebService
      name: frontend-v1 # user will be responsible to maintain and provide this name
      traits:
        - kind: Ingress
          properties:
            host: "www.example.com"
            path: "/"
      scopes:
        - my-vpc-network

#### Rollout

Rollout of the application will be managed by `AppDeployment`, it will perform pre-defined strategy for rollout or rollback (sometimes no action is needed).

# OAM Control Plane (In Reality Design)

考虑到现有的 Adoptor 和内部产品， OAM control plane 需要以兼容式的方式进行演进，不能直接引入上述 v1alpha3。具体路径在 KubeVela 中如下：
- 引入 `Application` 对象代替上述 v1alpha3 的 ApplicationConfiguration 来代表一个“应用”;
- `WorkloadDefinition` 和 `TraitDefinition` 名字和功能不变;
- 引入 Appfile 以及 Dashboard 作为系统 UI，其中 Appfile 与 `Application` 一一对应;
- `Application` 的 Controller 通过 CUE 引擎进一步渲染出 v1alpha2 的 Component 和 AppConfig，所以 C/AC 里面存放的已经是渲染后 Raw K8s 数据，这与今天现有 Adoptor 保持了兼容；
- C/AC 上的 dataInput/output 需要在 Application 层进行进一步的用户侧抽象（比如： incline function 和 dependsOn 语义）。

在这条路径下，v1alpha2 现有的 C/AC 对 KubeVela 的用户不可见，成为实现细节。 而 KubeVela 暴露出来的对象（均为 v1alpha2）是：
- 对最终用户：
- Application
- 等同于 v1alpha1 的 ApplicationConfiguration
- AppDeployment
- 新增发布对象
- 对 Platform Team：
- WorkloadDefinition
- 等同于 v1alpha1 的 ComponentSchematic
- TraitDefinition
- 等同于 v1alpha1 的 Trait
- ScopeDefinition
- 无变化

上述对象，即可认为是 OAM Spec v1alpha2 的终态，可以看到，v1alpha1 的 C/AC 其实被保留下来作为 WorkloadDefinition/Application 存在了。