component-schematic.md

Component Schematic

A component schematic is a resource that declares the operational characteristics of a module of code in infrastructure neutral terms. It describes a functional code unit, or microservice, that can be instantiated as part of one or more larger distributed applications. You can instantiate a component by first defining its schematic (ComponentSchematic), installing it to your Rudr runtime, and then deploying an application configuration that references it.

The component schematic is managed as part of the developer role.

The key parts of a component schematic include:

• Metadata: Information about the component.
• Workload type: Descriptor of the component's runtime profile.
• Parameters: (Optional). Configuration options of the component.
• Containers: Runnable pieces of code used by the component and their resource requirements.

Rudr schedules all the containers of a component to run on the same pod. You can implement a side-car pattern by including multiple containers in a single component schematic.

Here's an example application configuration (.yaml file):

apiVersion: core.oam.dev/v1alpha1
kind: ComponentSchematic
metadata:
  name: alpine-forever-v1
spec:
  workloadType: core.oam.dev/v1alpha1.SingletonServer
  parameters:
    - name: message
      type: string
      required: false
    - name: unused_integer
      type: number
      required: false
      default: 5678
  containers:
    - name: runner
      image: technosophos/alpine-forever:latest
      env:
        - name: FOO
          value: bar
          fromParam: message
        - name: UNUSED
          value: "1234"
          fromParam: unused_integer

To create a component schematic, you'll first need the containerized code that will constitute your microservice. From there, you might want to start with a template like the one above (or in the provided examples) and customize to your needs.

Common operations

Here are the key operations for installing and managing components.

Install a component:

$ kubectl apply -f <component-schematic>.yaml

List installed components:

$ kubectl get componentschematics

List details of a specific component:

$ kubectl get componentschematic <component-name> -o yaml

Delete a component:

$ kubectl delete componentschematic <component-name>

The remaining sections will walk you through the key aspects and options of a component schematic.

Metadata

The metadata section provides information about the object represented by this schematic (in this case, the ComponentSchematic), including its name, and optionally, any labels or annotations in the form of key/value pairs.

The metadata section consists of the following fields:

Name	Description	Allowable values	Required	Default
name	The identifier you'll use to manage your component with kubectl (designated as <component-name> in the commands above).	string	☑
labels	A set of string key/value pairs assigned to the component.	Use OAM/Kubernetes label format.
annotations	Further metadata in key/value format describing the component, such as version and description.	Use OAM/Kubernetes label format. version and description are pre-defined in OAM and considered best practices.

Here's an example of how to specify a label and annotations:

# Example annotations in component schematic
metadata:
  name: frontend
  labels:
    release: canary
  annotations:
    version: v1.0.0
    description: "Frontend component of the application"

Workload type

A component must declare its associated workload type, which is an indicator to the runtime as to how the developer intends for this component to be executed.

See the Workload types topic guide for more on choosing a workload type for your component.

Here's an example declaration of the component workload type:

workloadType: core.oam.dev/v1alpha1.Server

Parameters

The (optional) parameters section defines the configurable parameters for the component. Parameters defined here can be referenced as environment variables within the containerized code of your component.

The parameters section includes the following fields:

Name	Description	Allowable values	Required	Default
name	Identifier of the parameter	string. Must be unique per component.	☑
description	Description of the parameter.	string
type	JSON type of the parameter.	boolean, number, string, or null	☑
required	Whether a value must be provided.	true or false		false
default	Default value of the parameter.	Depends on specified parameter type.

Here's an example of declaring parameters and then referencing them (fromParam) as environment variables from a container:

# Example parameter declaration/reference in component schematic
parameters:
  - name: message
    type: string
    required: false
  - name: unused_integer
    type: number
    required: false
    default: 5678
containers:
  - name: runner
    image: technosophos/alpine-forever:latest
    env:
      - name: FOO
        value: bar
        fromParam: message
      - name: UNUSED
        value: "1234"
        fromParam: unused_integer

Containers

The containers section describes the runtime configuration required to run a containerized workload for the component. The container definition in Rudr is based on the Kubernetes container spec, however in Rudr you can also inject config files into a container. Configs in the container are implemented using Kubernetes ConfigMaps.

A component schematic requires one or more containers, each consisting of the following fields:

Name	Description	Allowable values	Required	Default
name	Name of the container.	string. Must be unique per component.	☑
image	A path or URI of the location of the container image.	string. Best practice is to include a tag suffix.	☑
resources	The runtime resources (such as CPU, memory, and storage) required by the container.	string. See resources section for details.	☑
ports	The ports exposed by the container.	See ports section for details.
cmd	The command to run when the container starts.	string. Supply any arguments using the args field (see below).
args	Arguments to the cmd entrypoint.	string
env	Environment variables for the container.	See env section for details.
config	Location(s) to write configuration files within the container.	See config section for details.

Here's an example definition within the containers section of the component schematic:

# Example container entry in component schematic
containers:
  - name: foo
    image: nginx:latest
    cmd:
      - nginx-debug
    args:
      - "-g"
      - "daemon off;"
    env:
      - name: TEST
        value: FOO
    config:
      - path: "/etc/access/default_user.txt"
        value: "admin"
      - path: "/etc/run/db-data"
        fromParam: "poet"
    ports:
      - protocol: TCP
        containerPort: 80
        name: http

resources

The resources section describes compute resources attached to a container runtime.

The resources section includes the following fields:

Name	Description	Allowable values	Required	Default
cpu	The minimum number of logical CPUs required for running the container.	double. (Fractional values supported.)	☑
memory	The minimum amount of memory required for running the container.	string. Use OAM notation. Must be greater than zero.	☑
gpu	The minimum number of gpus required for running this container.	double. (Fractional values supported.)
volumes	Specifies the attributes of the volumes that the container uses.	See volumes section for details.

Here's an example resources section of the component schematic:

# Example resources section in component schematic
resources:
  cpu:
    required: "0.5"
  memory:
    required: "128"

volumes

Use the volumes section to specify the volume mounts used by the container for persistent storage.

Entries for the volumes section include the following fields:

Name	Description	Allowable values	Required	Default
name	The name used to reference the mount.	string	☑
mountPath	Filesystem path of the mount.	string	☑
sharingPolicy	The sharing policy for the mount, indicating if it is expected to be shared or not.	Exclusive or Shared.	☑
accessMode	Access mode for the mount.	RW (read/write) or RO (read-only).		RW
disk	Attributes of the underlying disk resources, including minimum required disk size for running the container and whether (boolean) the disk is ephemeral	For required disk size, use OAM notation. ephemeral takes a boolean value.

Here's an example entry to the volumes section:

# Example volume entry
volumes:
  - name: "configuration"
    mountPath: /etc/config
    accessMode: RO
    sharingPolicy: Shared
    disk:
      required: "2G" # request at least 2GB
      ephemeral: n   # non-ephemeral storage

ports

The ports section describes the ports exposed by the container.

Entries to the ports section include the following fields:

Name	Description	Allowable values	Required	Default
name	Descriptive name for the port.	string. Must be unique per container.	☑
containerPort	The port number.	int. Must be unique per container.	☑
protocol	Transport layer protocol used by the server listening on the port.	TCP or UDP		TCP

Here's an example entry to the ports section:

# Example port entry
ports:
  - protocol: TCP
    containerPort: 9999
    name: http

env

The env section describes environment variables for the container as name/value string pairs.

Entries to the env section include the following fields:

Name	Description	Allowable values	Required	Default
name	The environment variable name.	string. Must be unique per container.	☑
value	The environment variable value.	string. If not supplied, fromParam must be supplied.
fromParam	The parameter that should be substituted into this variable as a value.	string. Name of a key/value pair defined in the parameters section.

Here's an example entry to the env section:

# Example environment variable entry
env:
  - name: FOO
    value: bar
    fromParam: message # defined in parameters section of component spec

config

The config section describes a path to a file available within the container, as well as the data that will be written into that file. This provides a way to inject configuration files into a container.

Entries to the config section include the following fields:

Name	Description	Allowable values	Required	Default
path	An absolute path within the container.	string	☑
value	The data to be written into the file at the specified path.	string. If this is not supplied, fromParam must be supplied.
fromParam	The parameter whose value should be written into this file as a value.	string. Name of a key/value pair defined in the parameters section.

Here's an example entry to the config section:

# Example config entry
config:
  - path: "/etc/access/default_user.txt"
    value: "admin"
  - path: "/etc/run/db-data"
    fromParam: "poet"