Merge pull request oam-dev#416 from resouer/control-plane

Add control plane objects

1.purpose_and_goals.md

@@ -1,8 +1,8 @@
 # 1. Purpose and Goals
 
-The main goal of Open Application Model is to enable platform builders to create cloud native application platforms with a standard, runtime-agnostic model. The specification is designed to be agnostic to any specific container runtime, orchestration software, cloud provider, or hardware configuration, with clearly defined roles for developers, operators and platform builders, while still allowing implementations to make use of the native APIs, tools, and features that are unique to the implementation and its underlying runtime.  
+The main goal of Open Application Model is to enable developers describe cloud native application in simple, easy and runtime-agnostic approach, and allow platform builders to create such platforms with a standard model. The specification is designed to be agnostic to any specific container runtime, orchestration software, cloud provider, or hardware configuration, with clearly defined roles for developers, operators and platform builders, while still allowing implementations to make use of the native APIs, tools, and features that are unique to the implementation and its underlying runtime.  
 
-The central problem this specification seeks to address is: when building a cloud native platform, how the distributed applications can be modeled and handed off to those responsible for operating them.
+The central problem this specification seeks to address is: when creating a developer facing platform, how the distributed applications can be modeled and handed off to those responsible for operating them.
 
 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.
 
@@ -13,12 +13,13 @@ This specification provides a description of such applications, where the descri
 Additional goals of the specification are to:
 
 - Define __roles and responsibilities__ with respect to the component and application models.
-- Define __building-block objects__ for platform builders.
+- Define __user facing objects__ for developers,
+- Define __control plane objects__ for platform builders.
 - Promote the genesis of multiple, __differentiated__ implementations of both tooling and runtimes which can operate on a common class of components and applications.
 
 Non-goals include:
 
-- Defining or prescribing specific development or operational workflows.
+- Defining or prescribing specific orchestrating workflow.
 - Defining the schemas of operational resources, for example (but not limited
   to):
   - Secrets (secure, encrypted values)

2.overview_and_terminology.md

@@ -12,11 +12,17 @@ This specification proposes a model that defines cloud native applications as fo
 
 > 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.
 
-To enable platform builders implement the above model on any runtime infrastructure, the specification is designed as two categories: _Building Block Objects_ and _User Interface Objects_.
+To enable implementing the above model easily on any runtime infrastructure, the specification is designed as two categories: _Control Plane Objects_ and _User Interface Objects_. 
 
-### Building Block Objects
+In practice, developers are expected to interact with User Interface Objects only, and in the implementation, User Interface Objects will be translated to the Control Plane Objects. Thus, platform builders only need to implement Control Plane Objects on different runtime infrastructures. This would guarantee the runtime-agnostic of the whole specification but leaves great flexibility in the implementations on both developer and platform builder side.
 
-Building Block Objects specification defines the following application constructs for platform builders to model capabilities of runtime infrastructure in application-centric approach.
+### User Interface Objects
+
+User Interface Objects specification defines the modeling language for application developers to design and operate applications on any OAM based platform. The detailed specification is currently under design.
+
+### Control Plane Objects
+
+Control Plane Objects specification defines modeling objects for platform builders to model capabilities of any runtime infrastructure in application-centric approach.
 
 - __Component__, which defines a runnable unit and declares its characteristics _in infrastructure neutral terms_.
 - __Traits__ for assigning operational features to instances of components.
@@ -33,19 +39,10 @@ In addition, the specification defines the following definition constructs for i
 - __Trait Definition__, where platforms register the schema of a specific kind of trait.
 - __Scope Definition__, where platforms register 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, and platform builders are free to register any capability as new workload types or traits/scopes. This essentially bring an application centric but highly extensible abstraction layer for any runtime which implemented OAM primitives.
+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, and platform builders are free to register any capability as new workload types or traits/scopes. This essentially bring an application centric but highly extensible abstraction layer for any runtime which implemented OAM control plane primitives.
 
 ![alt](./assets/all-in-one.png)
 
-
-### User Interface Objects
-
-User Interface Objects specification defines the modeling language for application developers and application operators to design and operate applications with OAM based application platform. In most scenarios, User Interface Objects will be used to generate and manage the Building Block Objects.
-
-> PLACE HOLDER: This section is still under design.
-
-
-
 ## Terminology
 
 The following terms are used throughout this specification.
@@ -57,8 +54,9 @@ __Components__ enable application __developers__ to declare the characteristics
 A component is composed of the following pieces of information:
 
 - Metadata: Information _about_ the component, primarily directed toward the application operator
-- Workload template: A template about how to configure this component according to its workload definition
-- Parameters: The parameters that can be adjusted during application runtime
+- Workload Type: A declaration about what kind of capability this component relies upon
+- Workload Settings: A declaration about configurations to run this component. For example, resource requirements, runnable pieces (OCI images, functions, etc.), etc.
+- Parameters: The parameters that can be adjusted during operation time
 
 ### Traits
 
@@ -92,11 +90,11 @@ An application configuration has the following parts:
 
 ### Definition Objects
 
+Definition objects are used by OAM platform to register, discover and manage workload types, traits, and application scopes.
 
 #### 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:
+A platform that implements OAM defines each type of workload that a component can run 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

3.component.md

@@ -2,7 +2,7 @@
 
 This section defines components.
 
-The role of a component is to enable developers use OAM application platform to declare, in infrastructure-neutral format, the characteristics of a discrete unit of execution.
+The role of a component is to enable developers to declare, in infrastructure-neutral format, the characteristics of a discrete unit of execution.
 
 Components describe functional units that may be instantiated as part of a larger distributed application. For example, each microservice in an application is described as a component. The description itself is not an instance of that microservice, but a declaration of the operational capabilities of that microservice. The [Application Configuration](7.application_configuration.md) describes how components are grouped together and how instances of those components are then configured.
 

README.md

@@ -7,33 +7,32 @@
 
 Open Application Model (OAM) is a runtime-agnostic specification for defining cloud native applications and enable building application-centric platforms by natural.
 
-Focused on **application** rather than container or orchestrator, _Open Application Model_ brings modular, extensible, and portable design for building application centric platforms on any runtime systems like Kubernetes, cloud, or IoT devices.
+Focused on **application** rather than container or orchestrator, _Open Application Model_ brings modular, extensible, and portable design for modeling cloud native applications and enable building application-centric platforms on any runtime infrastructure like Kubernetes, cloud, or IoT devices.
 
 ### Why Open Application Model?
 
-Building platforms without application context is hard:
+Platforms without application context is hard:
 
 - Developers spend time on infrastructure details instead of applications - ingress, labels, iptables rules, DNS, etc, and learning how the platform is implemented.
 - Restricted platform capabilities - in-house APIs with opinionated abstractions and implementations, lack of interoperability.
 - Runtime lock-in - platform is tightly coupled with execution runtime, which heavily impact on how you configure, develop and operate your application.
 
 In Open Application Model, we propose an app-centric approach instead:
 
-- Application first - build the platform around a self-contained app model, where operational characteristics are also part of app definition, free of infrastructure here.
+- Application first - build the platform around a self-contained app model, where operational features as part of app definition, free of infrastructure here.
 - Clarity and extensibility - an open standard to modularize your platform capabilities into reusable pieces, with freedom to bring your own abstractions and implementations.
 - Runtime agnostic - a consistent experience to deploy and operate your apps across on-prem clusters, cloud providers or even edge devices.
 
-> **NOTICE:** The current working draft of OAM specification (0.2.x release) is under pre-beta release, which means the specification is still under development but will keep backward compatibility for any further change.
+> **NOTICE:** The current working draft of OAM specification (0.2.x release) is under pre-beta release, it's still under development but will keep backward compatibility for any further change.
 
 ## Introduction
 
 _"Developers think in terms of application architecture, not of infrastructure."_
 
-Open Application Model defines a series of standard but extensible building blocks to model micro-service applications, with day 2 operations as part of the application definition. This enables platform builders to create platforms around a unified model, with app-centric mindset by default, and essentially changes building platforms into developing modularized components and traits for the application. 
+Open Application Model defines a series of standard but extensible abstractions to model micro-service applications, with operation features as part of the application definition. This enables platform builders to create runtime-agnostic systems around a unified model, by developing modularized components and traits, and essentially serve their customers (e.g. developers) with app-centric mindset by default.
 
 ![How it works](assets/how-it-works.png)
 
-
 ### Team-centric and separation of concerns
 
 Open Application Model proposed a clear separation of concerns between the parts that developers are responsible for, and the parts that operators and platform engineers are responsible for. For more details, see [introduction.md](./introduction.md).
@@ -47,7 +46,7 @@ Open Application Model proposed a clear separation of concerns between the parts
 
 ## See it in action
 
-- [OAM Kubernetes Runtime](https://github.com/crossplane/oam-kubernetes-runtime) is the officially maintained OAM plugin for Kubernetes which implemented OAM building block objects.
+- [KubeVela](https://github.com/oam-dev/kubevela): the highly extensible application platform based on Kubernetes and OAM.
 
 ## Community
 

SPEC.md

@@ -22,7 +22,14 @@ Learn more about versioning [below](#versioning).
 
 ## The Specification Components
 
-**Building Block Objects**
+**User Interface Objects**
+
+|                                | Category      |         API Version            |
+| :----------------------------: | :-----------: | :----------------------------: |
+| Application  | standard | [WIP](https://github.com/oam-dev/spec/issues/306)   |
+| Application Deployment | standard | [WIP](https://github.com/oam-dev/spec/issues/342) |
+
+**Control Plane Objects**
 
 |                                | Category      |         API Version            |
 | :----------------------------: | :-----------: | :----------------------------: |
@@ -42,18 +49,9 @@ Learn more about versioning [below](#versioning).
 | Network Scope  | standard |  [v1alpha2](standard/scopes/network_scope.md)          |
 | Health Scope  | core |  [v1alpha2](core/scopes/health_scope.md)          |
 
-
-**User Interface Objects**
-
-|                                | Category      |         API Version            |
-| :----------------------------: | :-----------: | :----------------------------: |
-| Application  | standard | [WIP](https://github.com/oam-dev/spec/issues/306)   |
-| Application Deployment | standard | [WIP](https://github.com/oam-dev/spec/issues/342) |
-
-
 ## Versioning
 
-Open Application Model specification convention adopts [Kubernetes API resource convention](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/architecture/resource-management.md).
+For Control Plane Objects, Open Application Model specification convention adopts [Kubernetes API resource convention](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/architecture/resource-management.md).
 
 Releases of the specification are versioned according to [Semantic Versioning 2.0](https://semver.org/spec/v2.0.0.html) and described in [OAM release page](https://github.com/oam-dev/spec/releases). Implementations of the specification are required to specify which version they implement.