Merge pull request #321 from oam-dev/1.0.0-alpha2

1.0.0-alpha2 changes

1.purpose_and_goals.md

@@ -1,19 +1,12 @@
 # 1. Purpose and Goals
+
 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.  
 
-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.
+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.
 
 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.
 
-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.
-
-This open specification defines:
-
-- __Component schematics__, where developers declare the operational characteristics of the code they deliver _in infrastructure neutral terms_.
-- __Application scopes__, a way to group components into loosely coupled applications with common characteristics.
-- __Traits__ for assigning operational features to instances of components.
-- __Application configuration__, defines a deployment of components, their traits, and application scopes.
-- __Workload types and configurations__, which describe the underlying runtime for a particular workload, as well as exposing per-application configuration.
+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.
 
 Additional goals of the specification are to:
 
@@ -28,8 +21,8 @@ Non-goals include:
   - Secrets (secure, encrypted values)
   - Networks
   - Volumes
-- Describing or defining the runtimes themselves
+- Describing or defining the runtimes themselves.
 
-| Next Part        | 
+| Next Part     |
 | ------------- |
-| [2. Overview and Terminology](2.overview_and_terminology.md)| 
+| [2. Overview and Terminology](2.overview_and_terminology.md)|

3.workload.md

@@ -0,0 +1,134 @@
+# 3. Workload Definition
+
+**Target Role: Infrastructure Operator** 
+
+This section defines the workload definition schematics.
+
+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.
+
+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.
+
+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.  
+
+## 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 |
+|-----------|------|----------|---------------|-------------|
+| `apiVersion` | `string` | Y | | The specific version of the OAM specification in use. The core types use `core.oam.dev/v1alpha2` |
+| `kind` | `string` | Y || Must be `WorkloadDefinition` |
+| `metadata` | [`Metadata`](#metadata) | Y | | Information about the workload definition. |
+| `spec`| [`Spec`](#spec) | Y | | A container for the workload definition. |
+
+### Metadata
+
+The metadata section describes the workload definition. See [*metadata*](2.overview_and_terminology.md#Metadata).
+
+### Spec
+
+The specification section contains a reference to the workload definition.
+
+| Attribute | Type | Required | Default Value | Description |
+|-----------|------|----------|---------------|-------------|
+| `definitionRef` | [`DefinitionRef`](#DefinitionRef) | Y | | Workload schema reference. |
+
+#### DefinitionRef
+
+DefinitionRef defines an index to find the workload schema.
+
+| Attribute | Type | Required | Default Value | Description |
+|-----------|------|----------|---------------|-------------|
+| `name` | `string` | Y | | Name of the workload schema. |
+
+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.
+
+The following conventions are RECOMMENDED:
+
+- Use [Group/Version/Kind](2.overview_and_terminology.md#Group) to uniquely identify the schema.
+
+- `name` follows the format described in [*Group, Version, and Kind*](2.overview_and_terminology.md).
+
+- The `name` of the WorkloadDefinition is the same as the `name` to which it refers.
+
+    For example:
+
+    ```yaml
+    apiVersion: core.oam.dev/v1alpha2
+    kind: WorkloadDefinition
+    metadata:
+      name: schema.example.oam.dev
+    spec:
+      definitionRef:
+        name: schema.example.oam.dev
+    ```
+
+## Categories of Workload
+
+There are three categories of workloads:
+
+__Core workloads__ are the kind of workloads that every OAM runtime MUST implement according to spec definition.
+
+__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. 
+
+__Extended workloads__ are the kind of workloads that a OAM runtime is free to define.
+
+### Core Workload
+
+A core workload schema MUST be in the `core.oam.dev` group. OAM implementations MUST implement all core workloads as defined in this specification.
+
+Here is an example of a core workload definition:
+
+```yaml
+apiVersion: core.oam.dev/v1alpha2
+kind: WorkloadDefinition
+metadata:
+  name: x.core.oam.dev
+spec:
+  definitionRef:
+    name: x.core.oam.dev
+```
+
+### 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.
+
+```yaml
+apiVersion: core.oam.dev/v1alpha2
+kind: WorkloadDefinition
+metadata:
+  name: x.standard.oam.dev
+spec:
+  definitionRef:
+    name: x.standard.oam.dev
+```
+
+### Extended Workload
+
+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.
+
+ Here is an example of an extended workload:
+
+```yaml
+apiVersion: core.oam.dev/v1alpha2
+kind: WorkloadDefinition
+metadata:
+  name: foo.cache.io
+spec:
+  definitionRef:
+    name: foo.cache.io
+```
+
+## Core Workload definitions
+
+The following core workloads are defined in the OAM specification.
+
+### Containerized Workload
+
+A containerized workload is used for long-running workloads in containers. See [*Containerized Workload*](core/workloads/containerized_workload/containerized_workload.md).
+
+| Previous      | Next        |
+| ------------- |-------------|
+[2. Overview and Terminology](2.overview_and_terminology.md) | [4. The Component Model](4.component.md)|