3. Component Model

February 23, 2023 ยท View on GitHub

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.

alt

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

Top-Level Attributes

Here are the attributes that provide top-level information about the component definition.

AttributeTypeRequiredDefault ValueDescription
apiVersionstringYA 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
kindstringYMust be ComponentDefinition
metadataMetadataYEntity metadata.
specSpecYThe specification for the component definition.

Spec

AttributeTypeRequiredDefault ValueDescription
workloadWorkloadTypeDescriptorYIdentifier to workload type of this component.
schematicSchematicYSchematic information for this component.

WorkloadTypeDescriptor

AttributeTypeRequiredDefault ValueDescription
typestringYA reference to a WorkloadDefinition via name.
definitionWorkloadGVKYMutually exclusive to type, a reference to WorkloadDefinition via group, version, and kind.
WorkloadGVK
AttributeTypeRequiredDefault ValueDescription
apiVersionstringYThe API version the workload type.
kindstringYThe 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 deployment workflow. Note that OAM itself 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.

In KubeVela, following schematic implementations (cue, helm, kube) are supported for now.

Example

Below is a full example of CUE based component definition named webserver:

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 webserver 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
      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: sample
  • Raw Kubernetes API resource as component: sample.
Previous PartNext Part
2. Overview and Terminology4. Workload Types