3.component_model.md

3. Component Model

This section defines component model.

Components describe functional units that may be instantiated as part of a larger distributed application. The Application 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.

Component Definition

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 expose 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.

Top-Level Attributes

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 specification
kind	string	Y		Must be ComponentDefinition
metadata	Metadata	Y		Entity metadata.
spec	Spec	Y		The specification for the component definition.

Spec

Attribute	Type	Required	Default Value	Description
workload	WorkloadTypeDescriptor	Y		Identifier to workload type of this component.
schematic	Schematic	Y		Schematic information for this component.

WorkloadTypeDescriptor

Attribute	Type	Required	Default Value	Description
type	string	Y		A reference to a WorkloadDefinition via name.
definition	WorkloadGVK	Y		Mutually exclusive to type, a reference to WorkloadDefinition via group, version, and kind.

WorkloadGVK

Attribute	Type	Required	Default Value	Description
apiVersion	string	Y		The API version the workload type.
kind	string	Y		The API kind of the workload type.

Schematic

This section declares the schematic of a component that could be instantiated as part of an application in the later workflow.

Note that OAM specification has no enforcement on how to implement the schematic as long as it could:

1. model a deployable unit;
2. expose a JSON schema or equivalent parameter list.

Though in order to make the specification implementable, below schematic implementations (cue, helm, kube) are defined as part of the specification for now.

Note: hence below sections may change in the future releases.

Attribute	Type	Required	Default Value	Description
kube	Template	N		A template with parameter list for certain Kubernetes workload resource as component.
cue	Template	N		A CUE module as component.
helm	Template	N		A Helm chart as component.

kind: ComponentDefinition
...
  schematic:
    cue:
      template: |
        output: {
            ... template resource 1
        }
        // an extra template
        outputs: service: {
            ... template resource 2
        }
        parameter: {
            ... parameter list
        }

kind: ComponentDefinition
...
spec:
  workload:
    type: foo.bar
  schematic:
    helm:
      release:
        chart:
          spec:
            chart: "mychart"
            version: "5.1.4"
      repository:
        url: "http://oam.dev/catalog/"

kind: ComponentDefinition
...
  schematic:
    kube: 
      template:
        ... a Kubernetes deployment resource
      parameters: 
      - name: image
        required: true
        type: string
        fieldPaths: 
        - "spec.template.spec.containers[0].image"

Example

Below is a full example of CUE based component definition:

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
        }

With above ComponentDefinition installed in the platform, user would be able to deploy this component in an application as below:

apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
  name: webserver-demo
spec:
  components:
    - name: hello-world             # instance name
      type: webserver               # reference to the component definition
      properties:                   # parameter values
        image: crccheck/hello-world
        port: 8000
        env:
        - name: "foo"
          value: "bar"
        cpu: "100m"

Previous Part	Next Part
2. Overview and Terminology	4. Workload Types