Project: Open Application Model (App Definition and Development / Application Definition & Image Build)
File: 3.component_model.md

This section defines component model. Components describe functional units that may be instantiated as part of a larger distributed application. The section will describe how components are grouped together and how instances of those components are then configured, while this section will focus on component model itself. The role of a `ComponentDefinition` entity is to permit component providers to declare, in infrastructure-neutral format, the runtime characteristics of such unit of execution. For example, each microservice in an application is described as a component. Note that `ComponentDefinition` itself is NOT an instance of that microservice, but a declaration of the configurable attributes of that microservice. These configurable attributes should be exposed as a list of parameters which allow the application team to set and instantiate this component later at deployment time. In practice, a simple containerized workload, a Helm chart, or a cloud database may all be modeled as a component. Here are the attributes that provide top-level information about the component definition. | Attribute | Type | Required | Default Value | Description | |--||-||-| | `apiVersion` | `string` | Y | | A string that identifies the version of the schema the object should have. The core types uses `core.oam.dev/v1beta1` in this version of model | | `kind` | `string` | Y || Must be `ComponentDefinition` | | `metadata` | | Y | | Entity metadata. | | `spec`| | Y | | The specification for the component definition. | | Attribute | Type | Required | Default Value | Description | |--||-||-| | `workload` | | Y | | Identifier to of this component. | | `schematic` | | Y | | Schematic information for this component. | | Attribute | Type | Required | Default Value | Description | |--||-||-| | `type` | `string` | Y | | A reference to a `WorkloadDefinition` via name. | | `definition` | | Y | | Mutually exclusive to `type`, a reference to `WorkloadDefinition` via group, version, and kind. | | Attribute | Type | Required | Default Value | Description | |--||-||-| | `apiVersion` | `string` | Y | | The API version the workload

| | `kind` | `string` | Y || The API kind of the workload type. | This section declares the schematic of a component that could be instantiated as part of an application in the later deployment workflow. Note that OAM itself has no enforcement on how to implement the schematic as long as it could: model a deployable unit; expose a JSON schema or equivalent parameter list. In KubeVela, following schematic implementations (`cue`, `helm`, `kube`) are supported for now. Below is a full example of CUE based component definition named `webserver`: <p> <details> ```yaml apiVersion: core.oam.dev/v1beta1 kind: ComponentDefinition metadata: name: webserver annotations: definition.oam.dev/description: "webserver is a combo of Deployment + Service" spec: workload: definition: apiVersion: apps/v1 kind: Deployment schematic: cue: template: | output: { apiVersion: "apps/v1" kind: "Deployment" spec: { selector: matchLabels: { "app.oam.dev/component": context.name } template: { metadata: labels: { "app.oam.dev/component": context.name } spec: { containers: [{ name: context.name image: parameter.image if parameter["cmd"] != | { command: parameter.cmd } if parameter["env"] != | { env: parameter.env } if context["config"] != | { env: context.config } ports: [{ containerPort: parameter.port }] if parameter["cpu"] != | { resources: { limits: cpu: parameter.cpu requests: cpu: parameter.cpu } } }] } } } } // an extra template outputs: service: { apiVersion: "v1" kind: "Service" spec: { selector: { "app.oam.dev/component": context.name } ports: [ { port: parameter.port targetPort: parameter.port }, ] } } parameter: { image: string cmd?: [...string] port: *80 | int env?: [...{ name: string value?: string valueFrom?: { secretKeyRef: { name: string key: string } } }] cpu?: string } ``` </details> </p> With above `webserver` installed in the platform, user would be able to deploy this component in an application as below: ```yaml apiVersion: core.oam.dev/v1beta1 kind: Application metadata: name: webserver-demo spec: components: name: hello-world type: webserver # claim to deploy webserver component definition properties: # setting parameter values image: crccheck/hello-world port: 8000 # this port will be automatically exposed to public env: name: "foo" value: "bar" cpu: "100m" ``` Examples for other schematic formats: Helm component: Raw Kubernetes API resource as component: . | Previous Part | Next Part | | - |-| || |