diff --git a/2.overview_and_terminology.md b/2.overview_and_terminology.md index 84adf94..22f4975 100644 --- a/2.overview_and_terminology.md +++ b/2.overview_and_terminology.md @@ -35,7 +35,7 @@ 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 @@ -46,7 +46,7 @@ spec: ## Specification properties: image: "nginx" traits: - - name: scaler + - type: scaler properties: replicas: 2 ``` diff --git a/7.application_configuration.md b/7.application.md similarity index 53% rename from 7.application_configuration.md rename to 7.application.md index 6bc3cbb..d7ef5b1 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 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. -> The _Application_ was known as _ApplicationConfiguration_ in prior releases). +> Up to v0.3.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,45 +31,22 @@ 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 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` | [`[]Scope`](#scope) | N | | The scopes to be used in the component. A component joins a 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.| -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 - -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). - ##### 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`. 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`. -#### 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 will index a 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. #### Trait @@ -77,62 +54,63 @@ 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. +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 -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. +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 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 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 configurable elements of a component: its type, 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: + - 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 + scopes: + "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: + debug: "true" # debug is a parameter defined in the test-backend component. traits: - - name: scaler + - type: 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 + "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 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* 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 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). -## Workload instances and revisions of component +## Component instances and revisions of component instances -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 +118,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 80109bd..c1e19fe 100644 --- a/SPEC.md +++ b/SPEC.md @@ -16,7 +16,7 @@ Learn more about versioning [below](#versioning). 1. [Workload Types](4.workload_types.md) 1. [Application Scopes](5.application_scopes.md) 1. [Traits](6.traits.md) - 1. [Application](7.application_configuration.md) + 1. [Application](7.application.md) 1. [Practical Considerations](8.practical_considerations.md) 1. [Design Principles](9.design_principles.md)