Skip to content

Commit 77e5d2a

Browse files
hongchaodenghongchaodeng
authored
Merge pull request #321 from oam-dev/1.0.0-alpha2
1.0.0-alpha2 changes
2 parents df283de + 0b34041 commit 77e5d2a

21 files changed

+1790
-1617
lines changed

‎1.purpose_and_goals.md‎

Lines changed: 6 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,12 @@
11
# 1. Purpose and Goals
2+
23
The Open Application Model defines a standard, platform-agnostic way to describe cloud and edge applications. The goal of the specification is to provide a common way to describe applications agnostic to any specific container runtime, orchestration software, cloud provider, or hardware configuration, with clearly defined roles for developers and operators, while still allowing implementations to make use of the native APIs, tools, and features that are unique to the implementation and its underlying platform.
34

4-
The central problem this specification seeks to address is how distributed applications can be composed and then successfully handed off to those responsible for operating them. The problem is not so much about how to write programs, but how to take components of a service oriented (or microservice oriented) architecture, and streamline the workflow that surrounds such applications.
5+
The central problem this specification seeks to address is how distributed applications can be composed and handed off to those responsible for operating them. The problem is not so much about how to write programs, but how to take components of a service-oriented (or microservice-oriented) architecture, and streamline the workflow that surrounds such applications.
56

67
For example, a contemporary cloud application may be composed of dozens of microservices, each responsible for a discrete chunk of what, broadly speaking, is "an application." Such applications need to be configured, deployed, audited, updated, and deleted. Sometimes the application must be treated as a whole, and sometimes finer levels of granularity are required. And most importantly, often such applications are managed not by one person or one team, but by multiple teams who must cooperate to achieve reliability, stability, and timeliness.
78

8-
This specification provides a description of such applications, where the description is aimed at separating the concerns of developers from the concerns of operators. Furthermore, it suggests patterns and processes for managing such applications. The specification describes a model for cloud native (i.e. highly distributed) cloud applications, encompassing public cloud technologies, on-prem solutions, and IoT/edge technologies. By specifying a common model, this specification provides a foundation for multiple implementations of a shared description of cloud native applications.
9-
10-
This open specification defines:
11-
12-
- __Component schematics__, where developers declare the operational characteristics of the code they deliver _in infrastructure neutral terms_.
13-
- __Application scopes__, a way to group components into loosely coupled applications with common characteristics.
14-
- __Traits__ for assigning operational features to instances of components.
15-
- __Application configuration__, defines a deployment of components, their traits, and application scopes.
16-
- __Workload types and configurations__, which describe the underlying runtime for a particular workload, as well as exposing per-application configuration.
9+
This specification provides a description of such applications, where the description is aimed at separating the concerns of developers from the concerns of operators. Furthermore, it suggests patterns and processes for managing such applications. The specification describes a model for cloud native (i.e., highly distributed) applications, encompassing public cloud technologies, on-prem solutions, and IoT/edge technologies. By specifying a common model, this specification provides a foundation for multiple implementations of a shared description of cloud native applications.
1710

1811
Additional goals of the specification are to:
1912

@@ -28,8 +21,8 @@ Non-goals include:
2821
- Secrets (secure, encrypted values)
2922
- Networks
3023
- Volumes
31-
- Describing or defining the runtimes themselves
24+
- Describing or defining the runtimes themselves.
3225

33-
| Next Part |
26+
| Next Part |
3427
| ------------- |
35-
| [2. Overview and Terminology](2.overview_and_terminology.md)|
28+
| [2. Overview and Terminology](2.overview_and_terminology.md)|

‎2.overview_and_terminology.md‎

Lines changed: 89 additions & 56 deletions
Large diffs are not rendered by default.

‎3.component_model.md‎

Lines changed: 0 additions & 646 deletions
This file was deleted.

‎3.workload.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# 3. Workload Definition
2+
3+
**Target Role: Infrastructure Operator**
4+
5+
This section defines the workload definition schematics.
6+
7+
Workload definitions are authored by an infrastructure operator or platform builder. A workload definition defines the kind of components that an application developer can use in an application, along with the component's schema.
8+
9+
The purpose of workload definitions is to provide a way for an infrastructure operator or platform builder to define what components are available to application developers 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.
10+
11+
Usually, workload definitions are provided by the OAM runtime (just as traits are) so that application developers may inspect the OAM runtime and learn what workloads are available for use.
12+
13+
## Top-Level Attributes
14+
15+
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).
16+
17+
Here are the attributes that provide top-level information about the workload definition.
18+
19+
| Attribute | Type | Required | Default Value | Description |
20+
|-----------|------|----------|---------------|-------------|
21+
| `apiVersion` | `string` | Y | | The specific version of the OAM specification in use. The core types use `core.oam.dev/v1alpha2` |
22+
| `kind` | `string` | Y || Must be `WorkloadDefinition` |
23+
| `metadata` | [`Metadata`](#metadata) | Y | | Information about the workload definition. |
24+
| `spec`| [`Spec`](#spec) | Y | | A container for the workload definition. |
25+
26+
### Metadata
27+
28+
The metadata section describes the workload definition. See [*metadata*](2.overview_and_terminology.md#Metadata).
29+
30+
### Spec
31+
32+
The specification section contains a reference to the workload definition.
33+
34+
| Attribute | Type | Required | Default Value | Description |
35+
|-----------|------|----------|---------------|-------------|
36+
| `definitionRef` | [`DefinitionRef`](#DefinitionRef) | Y | | Workload schema reference. |
37+
38+
#### DefinitionRef
39+
40+
DefinitionRef defines an index to find the workload schema.
41+
42+
| Attribute | Type | Required | Default Value | Description |
43+
|-----------|------|----------|---------------|-------------|
44+
| `name` | `string` | Y | | Name of the workload schema. |
45+
46+
The workload schema definition itself MUST contain information that can be used to uniquely identify it. An OAM runtime will use that information in a [Component](4.component.md) to refer to the workload schema instead of using the name of the workload definition.
47+
48+
The following conventions are RECOMMENDED:
49+
50+
- Use [Group/Version/Kind](2.overview_and_terminology.md#Group) to uniquely identify the schema.
51+
52+
- `name` follows the format described in [*Group, Version, and Kind*](2.overview_and_terminology.md).
53+
54+
- The `name` of the WorkloadDefinition is the same as the `name` to which it refers.
55+
56+
For example:
57+
58+
```yaml
59+
apiVersion: core.oam.dev/v1alpha2
60+
kind: WorkloadDefinition
61+
metadata:
62+
name: schema.example.oam.dev
63+
spec:
64+
definitionRef:
65+
name: schema.example.oam.dev
66+
```
67+
68+
## Categories of Workload
69+
70+
There are three categories of workloads:
71+
72+
__Core workloads__ are the kind of workloads that every OAM runtime MUST implement according to spec definition.
73+
74+
__Standard workloads__ are the kind of workloads that a OAM runtime MAY implement. However, the implementation MUST strictly adhere to the schematics defined in the spec.
75+
76+
__Extended workloads__ are the kind of workloads that a OAM runtime is free to define.
77+
78+
### Core Workload
79+
80+
A core workload schema MUST be in the `core.oam.dev` group. OAM implementations MUST implement all core workloads as defined in this specification.
81+
82+
Here is an example of a core workload definition:
83+
84+
```yaml
85+
apiVersion: core.oam.dev/v1alpha2
86+
kind: WorkloadDefinition
87+
metadata:
88+
name: x.core.oam.dev
89+
spec:
90+
definitionRef:
91+
name: x.core.oam.dev
92+
```
93+
94+
### Standard Workload
95+
96+
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.
97+
98+
```yaml
99+
apiVersion: core.oam.dev/v1alpha2
100+
kind: WorkloadDefinition
101+
metadata:
102+
name: x.standard.oam.dev
103+
spec:
104+
definitionRef:
105+
name: x.standard.oam.dev
106+
```
107+
108+
### Extended Workload
109+
110+
Each OAM runtime may define its own workload definition beyond this specification. Any workload definition that is not part of the _core_ or _standard_ group is considered an extended workload. The name and schema of extended workloads are entirely at the discretion of the OAM implementation.
111+
112+
Here is an example of an extended workload:
113+
114+
```yaml
115+
apiVersion: core.oam.dev/v1alpha2
116+
kind: WorkloadDefinition
117+
metadata:
118+
name: foo.cache.io
119+
spec:
120+
definitionRef:
121+
name: foo.cache.io
122+
```
123+
124+
## Core Workload definitions
125+
126+
The following core workloads are defined in the OAM specification.
127+
128+
### Containerized Workload
129+
130+
A containerized workload is used for long-running workloads in containers. See [*Containerized Workload*](core/workloads/containerized_workload/containerized_workload.md).
131+
132+
| Previous | Next |
133+
| ------------- |-------------|
134+
[2. Overview and Terminology](2.overview_and_terminology.md) | [4. The Component Model](4.component.md)|

0 commit comments

Comments
 (0)