Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Refactor the spec documentation with better structure: #406

Merged
merged 3 commits into from
Sep 16, 2020
Merged

Refactor the spec documentation with better structure: #406

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5542477
Refactor the spec documentation with better structure:
resouer Sep 15, 2020
c098650
Update 4.workload_definitions.md
resouer Sep 16, 2020
c6f850d
Update 3.component.md
resouer Sep 16, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 15 additions & 9 deletions 3.component.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,9 @@ All component schematics are canonically represented as JSON and can be validate

### Top-Level Attributes

These attributes provide top-level information about the component definition.
The following attributes are common across all schemata defined in this document. They follow the [Kubernetes API convention](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields).

The attributes below provide top-level information about the component definition.

| Attribute | Type | Required | Default Value | Description |
|-----------|------|----------|---------------|-------------|
Expand All @@ -32,20 +34,24 @@ The spec defines the constituent parts of a component.
| `workload` | [`Workload`](#workload) | Y | | The specification of workload that should be passed to the runtime|
| `parameters` | [`[]Parameter`](#parameter) | N | | The component's configuration options. |

### Workload
#### Workload

The specification of workload which is composed by `type` and `spec`.

| Attribute | Type | Required | Default Value | Description |
|-----------|------|----------|---------------|-------------|
| `type` | string | Y | | The type of workload|
| `spec` | [`WorkloadSpec`](#workloadspec) | Y | | The template specification of workload. |
| `spec` | [`WorkloadSpec`](#workloadspec) | Y | | The specification template of workload. |

##### Type

In practice, the available workload types are registered by infrastructure operators/platform builders to the platform following OAM specification. We will explain this in detail in next chapter: [workload definitions](4.workload_definitions.md).

#### WorkloadSpec
##### WorkloadSpec

This section contains the specification of the workload whose [schema](4.workload_definitions.md#DefinitionRef) is referenced by the corresponding Workload Definition. The schema can be used to validated this section.

Note that `workload.spec` is designed as **template** for the instances of workload type. For example, a Component of `Server` type could generate multiple revisions of immutable Deployments such as `server-v1` and `server-v2` in Kubernetes runtime based on the `workload.spec` template.
Note that `WorkloadSpec` is designed as **template** for the instances of workload type. For example, a Component of `Server` type could generate multiple revisions of immutable Deployments such as `server-v1` and `server-v2` in Kubernetes runtime based on the `WorkloadSpec`.

### Parameters

Expand Down Expand Up @@ -114,11 +120,11 @@ spec:
- "spec.containers[0].env[0].value"
```

The component above assumes a `WorkloadDefinition` named `Server` exists in the system, for example: a [ContainerizedWorkload](core/workloads/containerized_workload/containerized_workload.md) definition.
> The component above assumes a `WorkloadDefinition` named `Server` exists in the system.

#### Implicit workload type

It is allowed for users to directly define `apiVersion` and `kind` instead of `workload.type` which implies the workload type is implicit, i.e. it's always same with the `WorkloadDefinition` with name of `containerizedworkloads.core.oam.dev`.
It is allowed for users to directly define `apiVersion` and `kind` instead of `workload.type` which indicates the workload type is implicit:

```yaml
apiVersion: core.oam.dev/v1alpha2
Expand All @@ -136,13 +142,13 @@ spec:
image: example/very-cool-workload:0.1.2@sha256:verytrustworthyhash
```

The component above assumes below `WorkloadDefinition` must exist in the system:
The component above will assume below `WorkloadDefinition` exist in the system:

```yaml
apiVersion: core.oam.dev/v1alpha2
kind: WorkloadDefinition
metadata:
name: containerizedworkloads.core.oam.dev
name: containerizedworkloads.core.oam.dev # <--- must be the same with apiGroup + Kind in the component, as well as the definitionRef.name below.
spec:
definitionRef:
name: containerizedworkloads.core.oam.dev
Expand Down
39 changes: 26 additions & 13 deletions 4.workload_definitions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,12 @@

This section defines the workload definition schematics.

Workload definitions are authored by an infrastructure operator (or platform builder). The purpose of workload definitions is to provide a way for an infrastructure operator (or platform builder) to register what workload types are available to application developers to define as component on a given platform. Workload definitions can define custom schemas for any type of workload. Examples include container pods, serverless functions, data stores, message queues, or any other kind of workload that an application developer needs to design a complete application.
Workload definitions are authored by an infrastructure operator/platform builder. The purpose of workload definitions is to provide a way for an infrastructure operator/platform builder to **register** what workload types are available to application developers to define as component on a given platform. Workload definitions can define custom schemas for any type of workload. Examples include container pods, serverless functions, data stores, message queues, or any other kind of workload that an application developer needs to design a complete application.

Usually, workload definitions are pre-installed or dynamically configured by infrastructure operators (just as traits are) so that application developers may inspect workload definition learn what workloads are available for use.
Usually, workload definitions are pre-installed or dynamically configured by infrastructure operators (just as traits are) so that application developers may inspect workload definition learn what workloads are available for use.

## Top-Level Attributes

The following attributes are common across all schemata defined in this document. They follow the [Kubernetes specification](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields).

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

| Attribute | Type | Required | Default Value | Description |
Expand All @@ -25,6 +23,28 @@ Here are the attributes that provide top-level information about the workload de

The metadata section describes the workload definition. See [*metadata*](2.overview_and_terminology.md#Metadata).

#### `Name`

The `name` of the workload definition indicates _the type of this workload_.
hongchaodeng marked this conversation as resolved.
Show resolved Hide resolved

The following workload types are available and enforced by OAM specification:

|Name|Category|Schema|Exposed|Replicable|Daemonized|
|-|-|-|-|-|-|
|[Server](core/workloads/server.md)|Core|[ContainerizedWorkload](core/workloads/schema/containerized_workload.md)|Yes|Yes|Yes
|[Task](core/workloads/task.md)|Standard|WIP|No|Yes|No

#### `Labels`

Infrastructure operators could add below reserved `labels` to workload definition to indicates _the distinguishing characteristics of this workload type_.

|Label|Type|Explain|
|-|-|-|
|`workload.oam.dev/replicable`|boolean|Whether they are replicable. If not, no replication or scaling traits may be assigned.|
|`workload.oam.dev/daemonized`|boolean|Whether they are daemonized. For daemon types, if the workload exits, this is considered a fault, and the system must fix it. For non-daemonized types, exit is considered a success if no error is reported.|
|`workload.oam.dev/exposed`|boolean|Whether they are exposed, i.e. have a service endpoint with a stable name for network traffic. Workload types that have a service endpoint need a virtual IP address (VIP) with a DNS name to represent the component as a whole, addressable within their network scope and can be assigned traffic routing traits.|
|`workload.oam.dev/podspecable`|boolean|Whether this workload can be addressed by Kubernetes `PodSpec`. If yes, the implementation could manipulate the workload by leveraging `PodSpec` structure, instead of being agnostic of the workload's schematic. |
Comment on lines +42 to +46
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

just for clarify, we haven't implemented this label mechanism yet.


### Spec

The specification section contains a reference to the workload definition.
Expand All @@ -46,7 +66,6 @@ The `definitionRef.name` itself MUST contain information that can be used to uni
The following conventions are RECOMMENDED:

- Use [Group/Version/Kind](2.overview_and_terminology.md#Group) to uniquely identify the schema.

- Use the `name` of the WorkloadDefinition indicates the workload type.

For example:
Expand Down Expand Up @@ -87,6 +106,8 @@ spec:
name: x.core.oam.dev
```

All core workload types are container-based, and assume that an implementation is capable of executing an OCI or Docker image as a container, and are capable of working with OCI registries.

### Standard Workload

A standard workload schema MUST be in the `standard.oam.dev` group. OAM implementations are NOT REQUIRED to implement standard workloads. However, if an implementation implements a workload that is already defined by a standard workload, it SHOULD use the standard workload definition as defined in this specification. Here is an example of a standard workload definition.
Expand Down Expand Up @@ -117,14 +138,6 @@ spec:
name: foo.cache.io
```

## Core Workload Types

The following core workload types are defined in the OAM specification.

### Server

A `Server` workload type is used for describing long-running container workloads with exposed ports. Please check [*Containerized Workload*](core/workloads/containerized_workload/containerized_workload.md) for its detailed definition.

| Previous | Next |
| ------------- |-------------|
[3. The Component Model](3.component.md) | [5. Application Scopes](5.application_scopes.md)|
2 changes: 1 addition & 1 deletion 5.application_scopes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ The spec defines the constituent parts of a scope.
| `allowComponentOverlap` | `bool` | Y | | Determines whether a component is allowed to be in multiple instances of this scope type simultaneously. When false, the runtime implementation MUST produce an error and stop deployment if an attempt is made to place a component into more than one instance of this scope type simultaneously. |
| `definitionRef` | [`DefinitionRef`](#definitionRef) | Y | | Index of the scope definition. |

### DefinitionRef
#### DefinitionRef

See [*DefinitionRef*](4.workload_definitions.md#DefinitionRef).

Expand Down
4 changes: 3 additions & 1 deletion 6.traits.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,9 @@ The specification defines two major things: The list of workloads to which this
| `appliesToWorkloads` | `[]string` | N | | The list of workloads to which this trait applies. If this field is empty or unspecified or specified as `"*"`, it means _any workload_. A trait must apply to at least one workload type. This attribute must contain at least one value. |
| `definitionRef` | [`DefinitionRef`](#definitionRef) | Y | | Index of the trait definition. |

### DefinitionRef
TODO: add back other fields in `TraitDefinition`; explain revision-aware trait.

#### DefinitionRef

See [*DefinitionRef*](4.workload_definitions.md#DefinitionRef).

Expand Down
38 changes: 22 additions & 16 deletions 7.application_configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,26 +4,30 @@

This section describes how applications are deployed using application configurations.

A component can be deployed into any number of runtimes, any number of times. Each deployment of a component is called an _instance_. Each time a component is deployed, it must be deployed _with a configuration_. This section of the specification describes configurations.

## Instances and revisions

A _instance_ or _workload instance_ is an instance of a component that is created during the deployment of an application configuration. It is created when a component is deployed together with a configuration.

- Each time a component is deployed, it must be deployed _with a configuration_. This section of the specification describes configurations.
- Each subsequent _upgrade_ of a component will modify the given instance, or generate a new revision of instance if any revision-aware traits are attached to the component.
- When an instance is first created, it is in its _initial revision state_. Each time an upgrade operation occurs, we say that a new _revision_ of that instance occurs. (There is, however, no assumption that there must be a corresponding `revision` object stored somewhere).

> For the purposes of this specification, workflow practices such as _rollback_ or _redeploy_ are considered to be special cases of _upgrade_ (that is, if the rules here apply to upgrade, they also apply to the other workflow practices). When a deployment of a component is _deleted_, the instance is considered to be deleted. This does not, however, imply that all data related to the instance must be deleted, or that deletion events cannot be recovered or undone.

An _application configuration_ (sometimes abbreviated to _configuration_) is managed by the _application operator_ role, and provides information specific to the current instance of a component. The following information is considered specific to the runtime instance of a component:

- Information about the particular instance, such as:
- Name
- Release version
- Revision
- Description
- Values for the defined `parameters` for a component, and for its respective components
- Trait assignments to add operational functionality, together with any trait configuration

## Instances and upgrades

An _instance_ is a trackable deployment of an application configuration. A _component instance_ is an instance of a component that is created during the deployment of an application configuration. It is created when a component is deployed together with a configuration. Each subsequent _upgrade_ of a component will modify the given instance after the application configuration is redeployed. And each subsequent upgrade of an application configuration can modify any of the component instances controlled by that application configuration. For the purposes of this specification, workflow practices such as _rollback_ or _redeploy_ are considered to be special cases of _upgrade_ (that is, if the rules here apply to upgrade, they also apply to the other workflow practices). When a deployment of a component is _deleted_, the instance is considered to be deleted. This does not, however, imply that all data related to the instance must be deleted, or that deletion events cannot be recovered or undone.

When an instance is first created, it is in its _initial release state_. Each time an upgrade operation occurs, we say that a new _release_ of that instance occurs. (There is, however, no assumption that there is a corresponding `release` object stored somewhere).
- Non revision-aware trait assignments, together with any trait configuration
- For revision-aware trait, it doesn't bind with specific revision of the instance because it may control multiple revisions at the same time.

### Releases

In [*Twelve-Factor Applications*](https://12factor.net/), a release is defined as a [build plus a set of configs](https://12factor.net/build-release-run). That is, any change to either a build or configuration produces a new release. In the Open Application Model, the analog is that component, trait, and scope definitions combined with an application configuration jointly constitute a release.
In [*Twelve-Factor Applications*](https://12factor.net/), a release is defined as a [build plus a set of configs](https://12factor.net/build-release-run). That is, any change to either a build or configuration produces a new release. In the Open Application Model, the analog is that component, trait, and scope objects combined with an application configuration jointly constitute a release.

For OAM applications, a release is defined thus:

Expand All @@ -40,6 +44,8 @@ To accommodate this definition of a release, an OAM platform SHOULD make the fol
* Traits similarly SHOULD be attached and detached according to the same guidelines
* Components' relationships to Application Scopes SHOULD be applied or removed according to the same guidelines

The releases can also be named as `Snapshot` according to the implementations.

## Runtime and Application Configuration

The [Workload](4.workload_definitions.md) chapter of the specification defines how schematics are constructed. The resulting schematics may then be used to instantiate a component on a OAM-compliant runtime.
Expand Down Expand Up @@ -72,7 +78,7 @@ The specification defines parameters that can be overridden at deployment time,
|-----------|------|----------|---------------|-------------|
| `components` | [`[]Component`](#component) | Y | | Component instance definitions. |

### Component
#### Component

This section defines the instances of components to create with the application configuration.

Expand All @@ -88,15 +94,15 @@ In addition to being unique, the `componentName` must follow these naming rules:

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

### Scope
#### Scope

The scope section defines the scope into which the component should be deployed.

| Attribute | Type | Required | Default Value | Description |
|-----------|------|----------|---------------|-------------|
| `scopeRef` | [`ScopeRef`](#scopeRef) | Y | | The reference information of the Scope. |

### ScopeRef
##### ScopeRef

The scopeRef section will index a scope instance by `apiVersion`, `kind` and `name`.

Expand All @@ -108,15 +114,15 @@ The scopeRef section will index a scope instance by `apiVersion`, `kind` and `na

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

### Trait
#### Trait

The trait section defines an instance of a trait.

| Attribute | Type | Required | Default Value | Description |
|-----------|------|----------|---------------|-------------|
| `trait` | [`TraitData`](#traitdata) | N | | Information required by a trait definition. |

#### TraitData
##### TraitData

The TraitData section contains the instantiation of the [schema](6.traits.md#DefinitionRef) referenced by the corresponding `traitDefinition`. The schema can be used to validated this section.

Expand All @@ -130,7 +136,7 @@ It is RECOMMENDED that `apiVersion` and `kind` are specified, for example:
replica: 2
```

### ParameterValue
#### ParameterValue

Values supplied to parameters that are used to override the parameters exposed by other types.

Expand Down
Loading