Skip to content

Latest commit

 

History

History
308 lines (202 loc) · 17.5 KB

2.overview_and_terminology.md

File metadata and controls

308 lines (202 loc) · 17.5 KB
Raw

2. Overview and Terminology

This section provides an overview of the Open Application Model (OAM) and its 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.

Roles and Responsibilities

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.

Overview of the Model

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.

This specification defines the following application constructs for application developers and application operators to design and operate applications:

  • Component, which defines an instance of a workload and declares its operational characteristics in infrastructure neutral terms.
  • Traits for assigning operational features to instances of components.
  • Application scopes, for grouping components into loosely coupled applications with common characteristics.
  • Application configuration, which delineates a deployment of components, their traits, and application scopes.

In addition, the specification defines the following definition constructs for infrastructure operators and platform builders to define the components, traits, and scopes that are available to application developers and application operators on a given platform:

  • Workload Definition, where platforms declare the schema of a specific kind of workload, such as containers, functions, or data stores, that developers use to create components.
  • Trait Definition, where platforms declare the schema of a specific kind of trait.
  • Scope Definition, where platforms declare the schema of a specific kind of application scope.

Thus, OAM defines an application as a collection of components each with a set of operational traits and scoped together into one or more application boundaries.

Terminology

The following terms are used throughout this specification.

Workload Definitions

A platform that implements OAM supplies a runtime (or runtimes) that can execute components. Each type of workload that a component can run by the OAM runtime is represented by a workloadDefinition that describes the following:

  • Metadata: Information about the workload kind
  • Definition reference: A reference to a schema that defines the workload. The schemas are mostly provided by the OAM platform.

Trait Definition

A platform that implements OAM defines the traits that are available on that platform using a traitDefinition that describes the following:

  • Metadata: Information about the trait kind
  • Definition reference: A reference to a schema that defines the trait.

Scope Definition

A platform that implements OAM defines the application scopes that are available on that platform using a scopeDefinition that describes the following:

  • Metadata: Information about the scope kind
  • Definition reference: A reference to a schema that defines the scope.

Component

Components enable 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 is composed of the following pieces of information:

  • Metadata: Information about the component, primarily directed toward the application operator
  • Workload spec: A specification about how to configure this component according to its workload definition
  • Parameters: The parameters that can be adjusted during application runtime

Traits

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 workloads types to which this trait applies
  • Definition reference: A reference to a schema that defines the trait

Application Scopes

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 represents 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
  • Allow overlap: Specifies whether a component can exist in multiple instances of the scope type
  • Definition reference: A reference to a schema that defines the scope

Application Configuration

An application configuration is a resource that declares how all parts of an application are to be instantiated and configured.

An application configuration has the following parts:

  • Metadata: Information about the installed application configuration
  • Components: A list of components to instantiate and run. Application operators apply traits to those component instances and supply values to parameters defined by the component author here.
  • Scopes: Setup application scopes

Representing OAM Objects as Schematics

The OAM specification represents OAM objects (workload definitions, 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 precludes the possibility of representing schematics as JSON documents or other similarly structured textual or binary representations.

The Structure of a Schematic

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/v1alpha2   ## Group and version
kind: Component                     ## Kind
metadata:                           ## Metadata
  name: nginx-replicated
spec:                               ## Specification
  workload: 
    apiVersion: core.oam.dev/v1alpha2
    kind: ContainerizedWorkload
    spec:
      os: linux
      containers:
        - name: server
          image: nginx:latest

The representational format used by OAM is derived from Kubernetes. However, OAM's design does not require Kubernetes.

Metadata

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

Attribute Type Required Default Value Description
name string Y A name for the schematic. name is subject to the restrictions listed beneath this table.
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 name Field

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/v1alpha2
kind: Component
metadata:
    name: foo
---
apiVersion: core.oam.dev/v1alpha2
kind: Trait
metadata:
    name: foo

Okay: Each group (one.dev and other.dev) allows the kind Component with name foo.

apiVersion: one.dev/v1alpha2
kind: Component
metadata:
    name: foo
---
apiVersion: other.dev/v1alpha2
kind: Component
metadata:
    name: foo

NOT Okay: Version is not a namespace qualifier.

apiVersion: core.oam.dev/v1alpha2
kind: Component
metadata:
    name: foo
---
apiVersion: core.oam.dev/v1
kind: Component
metadata:
    name: foo

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

Label Format

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 Format

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

Attribute Type Required Default Value Description
description string N A short description of the component.
version string N A user provided string defining the semantic version of the component, e.g. the release version of this software

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 filesystem

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

Group, Version, and Kind

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

This section describes the scheme.

Group

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.

Version

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:

  • v1
  • v2
  • v973

There are two additional modifiers that are part of the major version number:

  • alphaN (where N is one or more digits) indicates that this feature is experimental, and may be removed, but that its current compatibility marker is 1
  • betaN (where N is one or more digits) indicates that this feature is not yet stable. The N is 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:

  • v1alpha1
  • v973beta231

Compatibility is established by exact match only. v1 is not considered compatible with v2, v1alpha1, or v1beta2.

Versions do not have a uniqueness requirement.

Kind

The kind is the name of a type. For example, a component's kind is Component, 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 (e.g., HTTP, not Http).

Kinds MUST be unique within a group.

Representations of Group/Version/Kind

The fully qualified representation of Group/Version/Kind is GROUP/VERSION.KIND. Here are some examples:

  • local.dev/v7alpha2.Proxy
  • cache.example.com/v1.Redis
  • azure.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: Proxy

In 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. As a general rule, this behavior is NOT RECOMMENDED, but when 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. Workload Definition