From 576278490f6c04a4d8ac5ad86c297c9efe075ffe Mon Sep 17 00:00:00 2001 From: Daniel Higuero Date: Mon, 12 Apr 2021 20:50:46 +0200 Subject: [PATCH 1/7] New application entity --- 2.overview_and_terminology.md | 7 +- ...ation_configuration.md => 7.application.md | 122 ++++++++++-------- SPEC.md | 2 +- 3 files changed, 70 insertions(+), 61 deletions(-) rename 7.application_configuration.md => 7.application.md (57%) diff --git a/2.overview_and_terminology.md b/2.overview_and_terminology.md index af51ce4..70c0af9 100644 --- a/2.overview_and_terminology.md +++ b/2.overview_and_terminology.md @@ -34,19 +34,18 @@ Schematics all follow a similar pattern. Top-level attributes indicate the type The following example of a application exhibits all three of these sections: ```yaml -apiVersion: core.oam.dev/v1alpha2 ## Group and version +apiVersion: core.oam.dev/v1beta1 ## Group and version kind: Application ## Kind metadata: ## Metadata name: my-app spec: ## Specification -spec: components: - name: my-web-app-component type: webservice - settings: + properties: image: "nginx" traits: - - name: scaler + - type: scaler properties: replicas: 2 ``` diff --git a/7.application_configuration.md b/7.application.md similarity index 57% rename from 7.application_configuration.md rename to 7.application.md index 8bc8524..f21fade 100644 --- a/7.application_configuration.md +++ b/7.application.md @@ -1,8 +1,8 @@ # 7. Application -This section describes how applications are designed and deployed. +This section describes how applications are designed and deployed. An application represents the top-level entity in OAM, and defines which components will be instanciated once the application is deployed. In the _Application_ entity it is possible to specify the final parametrization of each component and the traits that are applied to augment their funcionality or alter their behavior. Additionally, a set of scopes grouping different subsets of components can be specified. -> The _Application_ was known as _ApplicationConfiguration_ in prior releases). +> Up to v3.0.0 of the current specification, the _Application_ was known as _ApplicationConfiguration_. ## Defining an application @@ -12,9 +12,9 @@ The top-level attributes of a application define its metadata, version, kind, an | Attribute | Type | Required | Default Value | Description | |-----------|------|----------|---------------|-------------| -| `apiVersion` | `string` | Y || A string that identifies the version of the schema the object should have. The core types uses `core.oam.dev/v1alpha2` in this version of specification. | +| `apiVersion` | `string` | Y || A string that identifies the version of the schema the object should have. The core types uses `core.oam.dev/v1beta1` in this version of specification. | | `kind` | `string` | Y || Must be `Application` | -| `metadata` | [`Metadata`](2.overview_and_terminology.md#metadata) | Y | | Information about the application. | +| `metadata` | [`Metadata`](metadata.md) | Y | | Information about the application. | | `spec`| [`Spec`](#spec) | Y || A specification for application attributes. | ### Spec @@ -31,19 +31,21 @@ This section defines the instances of components to create with the application. | Attribute | Type | Required | Default Value | Description | |-----------|------|----------|---------------|-------------| -| `name` | string | Y | | The name of the component. | -| `type` | string | Y | | The type of workload. | -| `settings` | [`WorkloadSettings`](#workloadsettings) | Y | | The workload-specific configuration. | +| `name` | string | Y | | The name of the component. This name may be used by the OAM runtime to name or associated generated entities. | +| `type` | string | Y | | A reference to the [Component](3.component.md) that will be instanciated by the application. Optionally a namespaced component may be referenced as `/`. The meaning of _namespace_ is implementation specific depending on the runtime being used and the target platform where entities are created. In the case of the Kubernetes OAM runtime, the concept of `namespace` matches the existing one in Kubernetes. | +| `properties` | [`Properties`](#properties) | N | | A set of values assigned to the parameters defined in the [component specification](3.component.md). | | `traits` | [`[]Trait`](#trait) | N | | The traits to attach to this component instance. | -| `scopes` | [`[]Scope`](#scope) | N | | The scopes to be used in the component. A component joins a scope by referencing it. | +| `scopes` | [`[]Scope`](#scope) | N | | The scopes the component belongs to. A component joins an application level scope by referencing it. | -In addition to being unique, the `name` must follow these naming rules: +The `name` must follow these naming rules: > 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. -##### Type +##### ComponentProperties -In practice, the available workload types are registered by infrastructure operators/platform builders to the platform following OAM specification. They are explained in detail in this chapter: [workload definition](4.workload_types.md). +A component may define a set of parameters that can be modified for each particular instance. + + upon instanciation. ##### WorkloadSettings @@ -51,6 +53,25 @@ This section is the location for specifying workload-specific configuration whos The implementation will use `WorkloadSettings` as the **template** to generate the instances of given workload type. For example, in Kubernetes implementation, a `Server` component would generate multiple immutable revisions of Deployment such as `frontend-v1` and `frontend-v2` upon every modification based on its `WorkloadSettings`. + +#### Trait + +The trait section defines an instance of a trait. + +| Attribute | Type | Required | Default Value | Description | +|-----------|------|----------|---------------|-------------| +| `name`| string | N | | The name of trait definition. This is used to reference to the definition/schema of the Trait. For one type of trait, there could be only one config/deploy in one component. | +| `properties`| [`Properties`](#properties) | N | | The configurable properties that are exposed by this trait. | + +> The `name` field must be 63 characters or less, beginning and ending with an alphanumeric character ([a-z0-9A-Z]) with dashes (-), underscores (_), dots (.), and alphanumerics between. + + +##### Properties + +Properties specify the values that are associated with the entity attributes. When associated with _Components_ the values set or overwrite the component available parameters. Component parametrization is discussed on the [Component](3.component.md) entity spec. + +Similarly, when properties are used on _Traits_ or _Scopes_ they set the values required by those entities to be instanciated. The structure is determined by the [definition reference](6.traits.md#DefinitionRef) of corresponding `TraitDefinition`. It may be a simple value, or it may be a complex object. Properties are validated against the schema appropriate for the trait or scope. + #### Scope The scope section defines the scope into which the component should be deployed. @@ -61,7 +82,7 @@ The scope section defines the scope into which the component should be deployed. ##### ScopeRef -The scopeRef section will index a scope instance by `apiVersion`, `kind` and `name`. +The scopeRef section identifies the associated scope instance by `apiVersion`, `kind` and `name`. | Attribute | Type | Required | Default Value | Description | |-----------|------|----------|---------------|-------------| @@ -71,68 +92,57 @@ 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 - -The trait section defines an instance of a trait. - -| Attribute | Type | Required | Default Value | Description | -|-----------|------|----------|---------------|-------------| -| `name`| string | N | | The name of trait definition. This is used to reference to the definition/schema of the Trait. For one type of trait, there could be only one config/deploy in one component. | -| `properties`| [`Properties`](#properties) | N | | The configurable properties that are exposed by this trait. | - -> The `name` field must be 63 characters or less, beginning and ending with an alphanumeric character ([a-z0-9A-Z]) with dashes (-), underscores (_), dots (.), and alphanumerics between. - - -##### Properties - -A properties object for trait is an object whose structure is determined by the [definition reference](6.traits.md#DefinitionRef) of corresponding `TraitDefinition`. It may be a simple value, or it may be a complex object. Properties are validated against the schema appropriate for the trait. - ## Example -The following is an example of a complete YAML file that expresses components and traits. This example illustrates the four configurational elements of a component: its name, workload settings, traits, and scopes. +The following is an example of a complete YAML file that expresses components, traits, and scopes. This example illustrates the four configurational elements of a component: its name, properties, traits, and scopes. ```yaml -apiVersion: core.oam.dev/v1alpha2 +apiVersion: core.oam.dev/v1beta1 kind: Application metadata: - name: my-app-deployment + name: my-example-app annotations: version: v1.0.0 - description: "Description of this deployment" + description: "Brief description of the application" spec: components: - - name: my-web-app-component - type: Server - settings: - containers: - - name: my-cool-workload - image: example/very-cool-workload:0.1.2@sha256:verytrustworthyhash - resources: - cpu: - required: 1.0 - memory: - required: 100MB - cmd: - - "bash lscpu" - ports: - - name: http - value: 8080 + - name: publicweb + type: web-ui + properties: # properties targeting component parameters. + image: example/web-ui:v1.0.2@sha256:verytrustworthyhash + param_1: "enabled" # param_1 is defined on the web-ui component traits: - - name: scaler + - name: ingress # ingress trait providing a public endpoint for the publicweb component of the application. + properties: # properties are defined by the trait CRD spec. This example assumes path and port. + path: / + port: 8080 + scopes: + - scopeRef: + apiVersion: core.oam.dev/v1alpha2 + kind: HealthScope + name: app-health # An application level health scope including both components. + - name: backend + type: company/test-backend # test-backend is referenced from other namespace + properties: + debug: "true" # debug is a parameter defined in the test-backend component. + traits: + - name: scaler # scaler trait to specify the number of replicas for the backend component properties: - replicas: 2 + replicas: 4 scopes: - scopeRef: apiVersion: core.oam.dev/v1alpha2 - kind: NetworkScope - name: example-vpc-network + kind: HealthScope + name: app-health # An application level health scope including both components. ``` -The example above illustrates a complete application, including its scopes, components and their traits. This application assumes a [WorkloadDefinition](4.workload_types.md) named `Server` and a [TraitDefinition](6.traits.md) named `scaler` are present in the runtime cluster. The templates defined in them will enforce the schema of this application. +The example above illustrates a complete application, including its scopes, components and their traits. This application assumes the existence of two [Components](3.component.md) representing the web user interface and the backend of an imaginary application. Two [Trait](6.traits.md) are used to augment the functionality of the components. First an scaler on the backend to set the replication factor, and an Ingress one to expose the application to the outside world. Additionally, a HealthScope is used to have a common point to check the status of both the web and backend components. This is an arbitrary set of components for the purpose of the example and not necessarilly requires all of them. + +Upon instanciation of the application, the runtime is expected to generated the required entities depending on the target system (e.g., Kubernetes) enforcing the schemas associated with each entity (e.g., a trait). As _Traits_ can be added to existing environments as extensions, the OAM runtime must be able to create any Trait entity that is registered on the system by means of a [TraitDefinition](6.traits.md##trait_definition). -## Workload instances and revisions of component +## Component instances and revisions of component -A _workload instance_ is an instance of a component that is created during the deployment of an application. It is created when a component is deployed together with a configuration. +A _component instance_ is created during the deployment of an application. 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. @@ -140,7 +150,7 @@ A _workload instance_ is an instance of a component that is created during the d > 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_ (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: +An _application_ 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 diff --git a/SPEC.md b/SPEC.md index 9cf0646..dd7ca57 100644 --- a/SPEC.md +++ b/SPEC.md @@ -16,7 +16,7 @@ Learn more about versioning [below](#versioning). 1. [Workload Definition](4.workload_types.md) 1. [Application Scopes](5.application_scopes.md) 1. [Trait Definition](6.traits.md) - 1. [Application Configuration](7.application_configuration.md) + 1. [Application](7.application.md) 1. [Practical Considerations](8.practical_considerations.md) 1. [Design Principles](9.design_principles.md) From 9a4755a1b631cb2a3c09fb0382aac5e6c89b15ad Mon Sep 17 00:00:00 2001 From: Daniel Higuero Date: Mon, 12 Apr 2021 20:54:29 +0200 Subject: [PATCH 2/7] Fix version --- 7.application.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/7.application.md b/7.application.md index f21fade..6b0f34c 100644 --- a/7.application.md +++ b/7.application.md @@ -2,7 +2,7 @@ This section describes how applications are designed and deployed. An application represents the top-level entity in OAM, and defines which components will be instanciated once the application is deployed. In the _Application_ entity it is possible to specify the final parametrization of each component and the traits that are applied to augment their funcionality or alter their behavior. Additionally, a set of scopes grouping different subsets of components can be specified. -> Up to v3.0.0 of the current specification, the _Application_ was known as _ApplicationConfiguration_. +> Up to v0.3.0 of the current specification, the _Application_ was known as _ApplicationConfiguration_. ## Defining an application From d7950f194fc4bcf6f3c74e93fdef31573a4bf9c3 Mon Sep 17 00:00:00 2001 From: Daniel Higuero Date: Thu, 15 Apr 2021 20:51:03 +0200 Subject: [PATCH 3/7] Apply suggestions from code review Co-authored-by: Hongchao Deng Co-authored-by: Jianbo Sun Co-authored-by: Lei Zhang (Harry) --- 7.application.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/7.application.md b/7.application.md index 6b0f34c..c574b72 100644 --- a/7.application.md +++ b/7.application.md @@ -33,7 +33,7 @@ This section defines the instances of components to create with the application. |-----------|------|----------|---------------|-------------| | `name` | string | Y | | The name of the component. This name may be used by the OAM runtime to name or associated generated entities. | | `type` | string | Y | | A reference to the [Component](3.component.md) that will be instanciated by the application. Optionally a namespaced component may be referenced as `/`. The meaning of _namespace_ is implementation specific depending on the runtime being used and the target platform where entities are created. In the case of the Kubernetes OAM runtime, the concept of `namespace` matches the existing one in Kubernetes. | -| `properties` | [`Properties`](#properties) | N | | A set of values assigned to the parameters defined in the [component specification](3.component.md). | +| `properties` | [`Properties`](#properties) | N | | A set of values assigned to the parameters exposed from the [component definition](3.component.md). | | `traits` | [`[]Trait`](#trait) | N | | The traits to attach to this component instance. | | `scopes` | [`[]Scope`](#scope) | N | | The scopes the component belongs to. A component joins an application level scope by referencing it. | @@ -60,7 +60,7 @@ The trait section defines an instance of a trait. | Attribute | Type | Required | Default Value | Description | |-----------|------|----------|---------------|-------------| -| `name`| string | N | | The name of trait definition. This is used to reference to the definition/schema of the Trait. For one type of trait, there could be only one config/deploy in one component. | +| `type`| string | N | | The name of trait definition. This is used to reference to the definition/schema of the Trait. For one type of trait, there could be only one config/deploy in one component. | | `properties`| [`Properties`](#properties) | N | | The configurable properties that are exposed by this trait. | > The `name` field must be 63 characters or less, beginning and ending with an alphanumeric character ([a-z0-9A-Z]) with dashes (-), underscores (_), dots (.), and alphanumerics between. @@ -94,7 +94,7 @@ The scopeRef section identifies the associated scope instance by `apiVersion`, ` ## Example -The following is an example of a complete YAML file that expresses components, traits, and scopes. This example illustrates the four configurational elements of a component: its name, properties, traits, and scopes. +The following is an example of a complete YAML file that expresses components, traits, and scopes. This example illustrates the four configurational elements of a component: its type, properties, traits, and scopes. ```yaml apiVersion: core.oam.dev/v1beta1 @@ -112,7 +112,7 @@ spec: image: example/web-ui:v1.0.2@sha256:verytrustworthyhash param_1: "enabled" # param_1 is defined on the web-ui component traits: - - name: ingress # ingress trait providing a public endpoint for the publicweb component of the application. + - type: ingress # ingress trait providing a public endpoint for the publicweb component of the application. properties: # properties are defined by the trait CRD spec. This example assumes path and port. path: / port: 8080 @@ -126,7 +126,7 @@ spec: properties: debug: "true" # debug is a parameter defined in the test-backend component. traits: - - name: scaler # scaler trait to specify the number of replicas for the backend component + - type: scaler # scaler trait to specify the number of replicas for the backend component properties: replicas: 4 scopes: @@ -140,7 +140,7 @@ The example above illustrates a complete application, including its scopes, comp Upon instanciation of the application, the runtime is expected to generated the required entities depending on the target system (e.g., Kubernetes) enforcing the schemas associated with each entity (e.g., a trait). As _Traits_ can be added to existing environments as extensions, the OAM runtime must be able to create any Trait entity that is registered on the system by means of a [TraitDefinition](6.traits.md##trait_definition). -## Component instances and revisions of component +## Component instances and revisions of component instances A _component instance_ is created during the deployment of an application. It is created when a component is deployed together with a configuration. From 61e7fb49d1fa8e85d2e735eda0f656f637b8395b Mon Sep 17 00:00:00 2001 From: Daniel Higuero Date: Thu, 15 Apr 2021 20:58:40 +0200 Subject: [PATCH 4/7] Apply comments and suggestions from PR --- 7.application.md | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/7.application.md b/7.application.md index c574b72..0a48f2b 100644 --- a/7.application.md +++ b/7.application.md @@ -41,12 +41,6 @@ The `name` must follow these naming rules: > 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. -##### ComponentProperties - -A component may define a set of parameters that can be modified for each particular instance. - - upon instanciation. - ##### WorkloadSettings This section is the location for specifying workload-specific configuration whose structure is determined by the [definition reference](4.workload_types.md#definitionref) of corresponding `WorkloadDefinition`. @@ -63,7 +57,7 @@ The trait section defines an instance of a trait. | `type`| string | N | | The name of trait definition. This is used to reference to the definition/schema of the Trait. For one type of trait, there could be only one config/deploy in one component. | | `properties`| [`Properties`](#properties) | N | | The configurable properties that are exposed by this trait. | -> The `name` field must be 63 characters or less, beginning and ending with an alphanumeric character ([a-z0-9A-Z]) with dashes (-), underscores (_), dots (.), and alphanumerics between. +Notice that _Traits_ do not require a name since it is the OAM runtime the one responsible of instanciating the traits. The name of the component is expected to be used for the associated traits. ##### Properties From a7060def01796f9811cca044a072dfa2559cf500 Mon Sep 17 00:00:00 2001 From: Daniel Higuero Date: Mon, 26 Apr 2021 15:21:34 +0200 Subject: [PATCH 5/7] Fix scope reference --- 7.application.md | 32 +++----------------------------- 1 file changed, 3 insertions(+), 29 deletions(-) diff --git a/7.application.md b/7.application.md index 0a48f2b..5a9c277 100644 --- a/7.application.md +++ b/7.application.md @@ -35,7 +35,7 @@ This section defines the instances of components to create with the application. | `type` | string | Y | | A reference to the [Component](3.component.md) that will be instanciated by the application. Optionally a namespaced component may be referenced as `/`. The meaning of _namespace_ is implementation specific depending on the runtime being used and the target platform where entities are created. In the case of the Kubernetes OAM runtime, the concept of `namespace` matches the existing one in Kubernetes. | | `properties` | [`Properties`](#properties) | N | | A set of values assigned to the parameters exposed from the [component definition](3.component.md). | | `traits` | [`[]Trait`](#trait) | N | | The traits to attach to this component instance. | -| `scopes` | [`[]Scope`](#scope) | N | | The scopes the component belongs to. A component joins an application level scope by referencing it. | +| `scopes` | `map[string]string` | N | | A map with the scopes the component belongs to. The map uses the qualified scope definition name as key (e.g., "scope.company.com"), and the name of the scope as value (e.g., "myscope"). Notice that this reference implies that an entity of the target scope with the specific name exists.| The `name` must follow these naming rules: @@ -66,26 +66,6 @@ Properties specify the values that are associated with the entity attributes. Wh Similarly, when properties are used on _Traits_ or _Scopes_ they set the values required by those entities to be instanciated. The structure is determined by the [definition reference](6.traits.md#DefinitionRef) of corresponding `TraitDefinition`. It may be a simple value, or it may be a complex object. Properties are validated against the schema appropriate for the trait or 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 - -The scopeRef section identifies the associated scope instance by `apiVersion`, `kind` and `name`. - -| Attribute | Type | Required | Default Value | Description | -|-----------|------|----------|---------------|-------------| -| `apiVersion` | `string` | Y | | The apiVersion of the Scope. | -| `kind` | `string` | Y | | The kind of the Scope. | -| `name` | `string` | Y | | The name of the Scope. | - -> 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. - ## Example The following is an example of a complete YAML file that expresses components, traits, and scopes. This example illustrates the four configurational elements of a component: its type, properties, traits, and scopes. @@ -111,10 +91,7 @@ spec: path: / port: 8080 scopes: - - scopeRef: - apiVersion: core.oam.dev/v1alpha2 - kind: HealthScope - name: app-health # An application level health scope including both components. + "healthscopes.core.oam.dev": "app-health" # An application level health scope including both components. - name: backend type: company/test-backend # test-backend is referenced from other namespace properties: @@ -124,10 +101,7 @@ spec: properties: replicas: 4 scopes: - - scopeRef: - apiVersion: core.oam.dev/v1alpha2 - kind: HealthScope - name: app-health # An application level health scope including both components. + "healthscopes.core.oam.dev": "app-health" # An application level health scope including both components. ``` The example above illustrates a complete application, including its scopes, components and their traits. This application assumes the existence of two [Components](3.component.md) representing the web user interface and the backend of an imaginary application. Two [Trait](6.traits.md) are used to augment the functionality of the components. First an scaler on the backend to set the replication factor, and an Ingress one to expose the application to the outside world. Additionally, a HealthScope is used to have a common point to check the status of both the web and backend components. This is an arbitrary set of components for the purpose of the example and not necessarilly requires all of them. From 22f50b830d27d0e1cc07e6e866a5559977eb8a5d Mon Sep 17 00:00:00 2001 From: Daniel Higuero Date: Mon, 26 Apr 2021 18:08:34 +0200 Subject: [PATCH 6/7] Fix merge --- SPEC.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/SPEC.md b/SPEC.md index 3c042d8..c1e19fe 100644 --- a/SPEC.md +++ b/SPEC.md @@ -15,13 +15,8 @@ Learn more about versioning [below](#versioning). 1. [Component Model](3.component_model.md) 1. [Workload Types](4.workload_types.md) 1. [Application Scopes](5.application_scopes.md) -<<<<<<< HEAD - 1. [Trait Definition](6.traits.md) - 1. [Application](7.application.md) -======= 1. [Traits](6.traits.md) - 1. [Application](7.application_configuration.md) ->>>>>>> master + 1. [Application](7.application.md) 1. [Practical Considerations](8.practical_considerations.md) 1. [Design Principles](9.design_principles.md) From 1113f1f3a1d53e6593ed20ee90fdda34cdf36f55 Mon Sep 17 00:00:00 2001 From: Daniel Higuero Date: Tue, 27 Apr 2021 09:27:21 +0200 Subject: [PATCH 7/7] Address PR comments --- 7.application.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/7.application.md b/7.application.md index d41ee47..d7ef5b1 100644 --- a/7.application.md +++ b/7.application.md @@ -1,6 +1,6 @@ # 7. Application -This section describes how applications are designed and deployed. An application represents the top-level entity in OAM, and defines which components will be instanciated once the application is deployed. In the _Application_ entity it is possible to specify the final parametrization of each component and the traits that are applied to augment their funcionality or alter their behavior. Additionally, a set of scopes grouping different subsets of components can be specified. +This section describes how applications are designed and deployed. An application represents the top-level entity in OAM, and defines which components will be instantiated once the application is deployed. In the _Application_ entity it is possible to specify the final parametrization of each component and the traits that are applied to augment their funcionality or alter their behavior. Additionally, a set of scopes grouping different subsets of components can be specified. > Up to v0.3.0 of the current specification, the _Application_ was known as _ApplicationConfiguration_. @@ -32,7 +32,7 @@ This section defines the instances of components to create with the application. | Attribute | Type | Required | Default Value | Description | |-----------|------|----------|---------------|-------------| | `name` | string | Y | | The name of the component. This name may be used by the OAM runtime to name or associated generated entities. | -| `type` | string | Y | | A reference to the [Component](3.component.md) that will be instanciated by the application. Optionally a namespaced component may be referenced as `/`. The meaning of _namespace_ is implementation specific depending on the runtime being used and the target platform where entities are created. In the case of the Kubernetes OAM runtime, the concept of `namespace` matches the existing one in Kubernetes. | +| `type` | string | Y | | A reference to the [Component](3.component.md) that will be instantiated by the application. Optionally a namespaced component may be referenced as `/`. The meaning of _namespace_ is implementation specific depending on the runtime being used and the target platform where entities are created. In the case of the Kubernetes OAM runtime, the concept of `namespace` matches the existing one in Kubernetes. | | `properties` | [`Properties`](#properties) | N | | A set of values assigned to the parameters exposed from the [component definition](3.component.md). | | `traits` | [`[]Trait`](#trait) | N | | The traits to attach to this component instance. | | `scopes` | `map[string]string` | N | | A map with the scopes the component belongs to. The map uses the qualified scope definition name as key (e.g., "scope.company.com"), and the name of the scope as value (e.g., "myscope"). Notice that this reference implies that an entity of the target scope with the specific name exists.| @@ -57,18 +57,18 @@ The trait section defines an instance of a trait. | `type`| string | N | | The name of trait definition. This is used to reference to the definition/schema of the Trait. For one type of trait, there could be only one config/deploy in one component. | | `properties`| [`Properties`](#properties) | N | | The configurable properties that are exposed by this trait. | -Notice that _Traits_ do not require a name since it is the OAM runtime the one responsible of instanciating the traits. The name of the component is expected to be used for the associated traits. +Notice that _Traits_ do not require a name since it is the OAM runtime that is responsible for instanciating the traits. The name of the component is expected to be used for the associated traits. ##### Properties -Properties specify the values that are associated with the entity attributes. When associated with _Components_ the values set or overwrite the component available parameters. Component parametrization is discussed on the [Component](3.component.md) entity spec. +Properties specify the values that are associated with the entity attributes. When associated with _Components_ the values set or overwrite the component's available parameters. Component parametrization is discussed on the [Component](3.component.md) entity spec. -Similarly, when properties are used on _Traits_ or _Scopes_ they set the values required by those entities to be instanciated. The structure is determined by the [definition reference](6.traits.md#DefinitionRef) of corresponding `TraitDefinition`. It may be a simple value, or it may be a complex object. Properties are validated against the schema appropriate for the trait or scope. +Similarly, when properties are used on _Traits_ or _Scopes_ they set the values required by those entities to be instantiated. The structure is determined by the [definition reference](6.traits.md#DefinitionRef) of corresponding `TraitDefinition`. It may be a simple value, or it may be a complex object. Properties are validated against the schema appropriate for the trait or scope. ## Example -The following is an example of a complete YAML file that expresses components, traits, and scopes. This example illustrates the four configurational elements of a component: its type, properties, traits, and scopes. +The following is an example of a complete YAML file that expresses components, traits, and scopes. This example illustrates the four configurable elements of a component: its type, properties, traits, and scopes. ```yaml apiVersion: core.oam.dev/v1beta1 @@ -104,9 +104,9 @@ spec: "healthscopes.core.oam.dev": "app-health" # An application level health scope including both components. ``` -The example above illustrates a complete application, including its scopes, components and their traits. This application assumes the existence of two [Components](3.component.md) representing the web user interface and the backend of an imaginary application. Two [Trait](6.traits.md) are used to augment the functionality of the components. First an scaler on the backend to set the replication factor, and an Ingress one to expose the application to the outside world. Additionally, a HealthScope is used to have a common point to check the status of both the web and backend components. This is an arbitrary set of components for the purpose of the example and not necessarilly requires all of them. +The example above illustrates a complete application, including its scopes, components and their traits. This application assumes the existence of two [Components](3.component.md) representing the web user interface and the backend of an imaginary application. Two [Trait](6.traits.md) are used to augment the functionality of the components. First an *scaler* on the backend to set the replication factor, and an *ingress* to expose the application to the outside world. Additionally, a HealthScope is used to have a common point to check the status of both the web and backend components. This is an arbitrary set of components for the purpose of the example and not necessarilly requires all of them. -Upon instanciation of the application, the runtime is expected to generated the required entities depending on the target system (e.g., Kubernetes) enforcing the schemas associated with each entity (e.g., a trait). As _Traits_ can be added to existing environments as extensions, the OAM runtime must be able to create any Trait entity that is registered on the system by means of a [TraitDefinition](6.traits.md##trait_definition). +Upon instantiation of the application, the runtime is expected to generate the required entities depending on the target system (e.g., Kubernetes) enforcing the schemas associated with each entity (e.g., a trait). As _Traits_ can be added to existing environments as extensions, the OAM runtime must be able to create any Trait entity that is registered on the system by means of a [TraitDefinition](6.traits.md##trait_definition). ## Component instances and revisions of component instances