This section provides an overview of the specification and the terminology. It begins by identifying the organization roles that are involved in the process of running cloud native applications. From there, it lays out the specific terminology that is used throughout this document.
As a foundation for the specification, the following roles are defined. These are extracted from a combination of user stories, research, and user input. While this is not an exhaustive list of possible roles, these are the roles identified as the primary targets for this specification.
-
Developers deliver business value in the form of code. While they should understand the operational characteristics of the code they deliver, they are unconcerned with how operational requirements are fulfilled. For instance, a developer may be aware that their code writes data to a specific path on a file system, but need not concern themselves with what kind of volume (disk) is mounted to that path or how that dependency is fulfilled.
-
Application operators deliver business value by configuring, installing, and managing components and/or applications such as updating, scaling, auto recovery, etc. Unlike developers and application composers, operators are concerned with how a component or application's operational requirements are fulfilled. For instance, if a developer has declared that a component writes data to a specific path on a file system, an operator may concern themselves with mounting an appropriate volume to that path.
-
Infrastructure operators deliver value by managing low-level infrastructural components. This may range from managing the physical hardware in an on-premises network to directly managing cloud service offerings in a public cloud. Infrastructure operators are less concerned with the particular configuration needs of an application, focusing instead on the big picture of how an enterprise's overall infrastructure is managed. For example, an infrastructure operator may manage the underlying storage offerings that are used for provisioning persistent storage.
In many organizations, some individuals may fulfill more than one of the above roles. And as the examples above illustrate, the roles often work together to collectively manage an enterprise's applications.
This specification proposes a model that defines cloud native applications as follows:
A cloud native application is a collection of interrelated, but discrete components (services, tasks, workers) that, when coupled with configuration and instantiated in a suitable runtime, together accomplish a unified functional purpose.
The application model defines the following:
- Components represents a runnable unit, together with a description (schematic).
- Workload types identify the different workloads that a component can execute.
- Traits are overlays that augment a component with additional operations-specific features. Traits represent operator concerns, not developer concerns.
- Application scopes represent application boundaries by grouping components with common properties or dependencies.
- An application configuration describes a set of component instances, their traits, and the application scopes in which they are placed, combined with configuration parameters and metadata.
Thus, an application is a collection of components with a set of operational traits and scoped together into one or more application boundaries.
The following terms are used throughout this specification.
Component schematics permit developers to declare the operational characteristics of the code they deliver in infrastructure neutral terms. Apart from not burdening developers with infrastructural concerns, this frees operators and runtimes to meet a component's infrastructural needs in whatever opinionated manner they see fit.
A component schematic is composed of the following pieces of information:
- A Workload Type: A declaration about what kind of runtime this component relies upon. (The platform will select a runtime that is capable of running this workload type.)
- Metadata: Information about the component, primarily directed toward the user
- Resource requirements: The additional minimum needs that must be satisfied in order for the component to be executed. For example, minimum memory, CPU, and filesystem mounts
- Parameters: The parameters that can be adjusted for specific runtime configuration
- Workload definition: A list of the runnable pieces (OCI images, functions, etc.) used by this component.
A platform that implements the Open Application Model (OAM) supplies a runtime (or runtimes) that can execute components. Each type of objects that can be run by the OAM runtime is represented by a workload type that describes the following:
- Metadata: Information about the workload type
- Workload Settings: Settings that an operator can provide to the workload for each component
A trait defines a piece of add-on functionality that pertains to the operation of a component. Traits may be limited to certain workload types. And different OAM implementations may supply or support a different set of traits. Traits represent features of the system that are operational concerns, not developer concerns. For example, a developer may know whether or not their component can be scaled (and so choose a workload type that declares this). But an operator may decide to apply a manual scaling trait or an autoscaler trait to this component.
A trait is described as:
- Metadata: Information about the trait
- Applies-to list: Enumeration of which workload types this trait applies to
- Properties: Configuration that may be specified in an application configuration
Application scopes provide different ways to group components into applications. Components are added to scopes by applying the name of the scope as a label on the component. Each scope has some associated behavior or functionality. For example, grouping components into a network application scope would provide network visibility to all components within the scope.
An application scope is described as:
- Metadata: Information about the scope
- Type: The type of scope. Different types of scopes provide different capabilities.
- Parameters: Configuration that may be specified in an application configuration
An application configuration is a resource that declares how an application (described as an application schematic and component schematics) can be instantiated and configured, including which parameter overrides and add-on traits.
An application configuration has the following parts:
- Metadata: Information about the installed application configuration
- Parameter Overrides: Values to supply to named parameters in the application or components
- Trait configuration: A list of traits to enable, together with parameter overrides for each trait
- Workload type settings: Overrides to workload type settings
The OAM specification represents OAM objects (components, trait definitions, application configurations, etc.) as schematics. A schematic is a structured document that provides a declaration of an object or an object's desired state. Throughout this specification, schematics are represented in YAML. However, nothing in this specification forecloses the possibility of representing schematics as JSON documents or other similarly structured textual or binary representations.
Schematics all follow a similar pattern. Top-level attributes indicate the type of schematic, including its group, version, and kind (see above). A metadata section provides information about a particular schematic. All schematics defined in this specification use the same metadata attributes, as defined below. Finally, a spec section provides the specification for the schematic. For example, the spec section of a Trait describes the trait itself, while the spec section of an Application Configuration describes the components and traits that together comprise an application deployment.
The following example of a Component exhibits all three of these sections:
apiVersion: core.oam.dev/v1alpha1 ## Group and version
kind: ComponentSchematic ## Kind
metadata: ## Metadata
name: nginx-replicated
spec: ## Specification
workloadType: core.oam.dev/v1alpha1.Server
os: linux
containers:
- name: server
image: nginx:latestThe representational format used by OAM is derived from Kubernetes. However, OAM's design does not require Kubernetes.
The metadata section is common across all defined schematics. It is made up of several top-level keys.
Metadata provides information about the contents of this object.
| Attribute | Type | Required | Default Value | Description |
|---|---|---|---|---|
name |
string |
Y | ||
labels |
map[string]string |
N | A set of string key/value pairs used as arbitrary labels on this component. See the "Label format" section immediately below. | |
annotations |
map[string]string |
N | A set of string key/value pairs used as arbitrary descriptive text associated with this object. See the "Annotations format" section immediately below. |
The combination of group, kind, name must be unique. Two different kinds (for example, a Component and a Trait) may have the same name and not cause conflicts. Version is not a distinguishing factor.
Okay: Each kind allows the name foo.
apiVersion: core.oam.dev/v1alpha1
kind: Component
metadata:
name: foo
---
apiVersion: core.oam.dev/v1alpha1
kind: Trait
metadata:
name: fooNOT Okay: Version is not a namespace qualifier.
apiVersion: core.oam.dev/v1alpha1
kind: Component
metadata:
name: foo
---
apiVersion: core.oam.dev/v1
kind: Component
metadata:
name: fooThe name field must be formatted as follows:
The name segment is required and must be 63 characters or less, beginning and ending with an alphanumeric character ([a-z0-9A-Z]) with dashes (-), underscores (_), dots (.), and alphanumerics between.
Unless otherwise noted, names must be unique within the Group/Version/Kind.
Labels follow the Kubernetes specification for labeling:
Valid label keys have two segments: an optional prefix and name, separated by a slash (/). The name segment is required and must be 63 characters or less, beginning and ending with an alphanumeric character ([a-z0-9A-Z]) with dashes (-), underscores (_), dots (.), and alphanumerics between. The prefix is optional. If specified, the prefix must be a DNS subdomain: a series of DNS labels separated by dots (.), not longer than 253 characters in total, followed by a slash (/).
Annotations provide a mechanism for attaching arbitrary text within the metadata of an object. The annotations object follows the Kubernetes specification:
Annotations are key/value pairs. Valid annotation keys have two segments: an optional prefix and name, separated by a slash (/). The name segment is required and must be 63 characters or less, beginning and ending with an alphanumeric character ([a-z0-9A-Z]) with dashes (-), underscores (_), dots (.), and alphanumerics between. The prefix is optional. If specified, the prefix must be a DNS subdomain: a series of DNS labels separated by dots (.), not longer than 253 characters in total, followed by a slash (/).
The following annotation labels are predefined and are strongly recommended.
| Attribute | Type | Required | Default Value | Description |
|---|---|---|---|---|
description |
string |
N | A short description of the component. | |
version |
string |
N | A string defining the semantic version of the component. |
If version is not supplied, the default version is assumed to be 0.1.0, per the SemVer specification.
Example:
metadata:
name: alpine-task
labels:
app: my-app-v1 # Non-normative example
annotations:
version: "1.0.1"
description: A task that is backed by an Alpine Linux filesystemThe metadata section is used in all schematics. It is also compatible with the Kubernetes metadata section. Note, however, that the Kubernetes metadata is a superset of the OAM metadata, and contains attributes that OAM does not recognize.
Many of the API objects described in this document use a naming scheme called "Group, Version, Kind." This scheme, popularized by Kubernetes, provides a consistent way of namespacing and versioning API objects, and it is used here for OAM API versioning.
Applications, components, containers, and other entities may have their own versioning schemes. This scheme is solely for the API objects like Component Schematic, Application Schematic, Workload Types, and Traits.
This section describes the scheme.
Group is a namespace for collecting several related kinds. Groups use a DNS naming convention. Example groups are:
- components.oam.dev
- functions.azure.com
- my.dev
All of the groups under the oam.dev domain are considered reserved for the specification. And all of the objects specified herein belong to groups in that domain.
Group MUST be globally unique.
The version string is an API version. Following the common paradigm, APIs are versioned by major number only. Minor and patch numbers are omitted from API versions. The actual minor and patch versions of the underlying engines may iterate, but they MUST iterate this version for any breaking change. In other words, the major number serves as a guarantee of compatibility, and minor and patch numbers should not change that guarantee. Therefore, consumers of the API cannot specify a finer granularity than the major version.
An API version number is always prefixed by a v, followed by one or more digits.
Examples:
v1v2v973
There are two additional modifiers that are part of the major version number:
alphaN(whereNis one or more digits) indicates that this feature is experimental, and may be removed, but that its current compatibility marker is1betaN(whereNis one or more digits) indicates that this feature is not yet stable. TheNis a compatibility marker.
API versions that are marked either alpha or beta are considered unstable and susceptible to breaking changes.
Only one of the two modifiers may be applied at a time:
v1alpha1v973beta231
Compatibility is established by exact match only. v1 is not considered compatible with v2, v1alpha1, or v1beta2.
Versions do not have a uniqueness requirement.
The kind is the name of a type. For example, a component schematic's kind is ComponentSchematic, while a trait's kind is Trait. Kinds are always composed of words where the initial letter is capitalized, and the first letter of every word is capitalized. Kinds should capitalize every letter of an acronym (HTTP, not Http).
Kinds MUST be unique within a group.
The fully qualified representation of Group/Version/Kind is GROUP/VERSION.KIND. Here are some examples:
local.dev/v7alpha2.Proxycache.example.com/v1.Redisazure.com/v2.Functions
In schematics, the group and version are presented on one field, and the kind is presented on another:
apiVersion: local.dev/v7alpha2
kind: ProxyIn rare cases, it is necessary to link a group and a kind, but without specifying a version. This is done, for example, when declaring default workload types. As a general rule, this behavior should be avoided whenever necessary, but when it is necessary, this specification follows the Kubernetes pattern of construct a DNS name out of the plural kind name and the group:
Proxies.local.dev # allowed but discouraged
This form is not accepted as an alternative for the fully qualified version. It is only accepted in cases where it is explicitly stated by the specification that this form is accepted.
| Previous Part | Next Part |
|---|---|
| 1. Purpose And Goals | 3. The Component Model |