---
# System prepended metadata

title: OAM Control Plane (Ideal Design)

---

# OAM Control Plane (Ideal Design)

## ComponentSchematic & Trait

```yaml=
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

```yaml=
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:

```console
$ 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

```yaml=
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 存在了。