Skip to content

Commit

Permalink
Refactor the spec documentation with better structure:
Browse files Browse the repository at this point in the history 
1. Clarify the intention that workload type is the NAME of workload definition.
2. Clarify ContainerizedWorkload as schema of Server workload type.
3. Create placeholder for Task workload type.
4. Fix several bugs
5. Remove SPEC_WORKING_DRAFT.md.
6. Rename SPEC_LATEST_STABLE.md to SPEC.md
7. Move specification components as part of SPEC.md, not readme.
  • Loading branch information
@resouer
resouer committed Sep 16, 2020
1 parent 6b70b87 commit d8eef93
Show file tree
Hide file tree
Showing 15 changed files with 202 additions and 155 deletions.
24 changes: 15 additions & 9 deletions 3.component.md
View file
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).

Below attributes 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
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_.

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

### 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
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
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
37 changes: 23 additions & 14 deletions 7.application_configuration.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,22 +4,29 @@

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.

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

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
- Non revision-aware trait assignments, together with any trait configuration

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

Expand All @@ -40,6 +47,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` based on the implementation.

## 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 +81,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 +97,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 +117,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 +139,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

0 comments on commit d8eef93

Please sign in to comment.