Skip to content

Latest commit

 

History

History
139 lines (98 loc) · 9.3 KB

7.application.md

File metadata and controls

139 lines (98 loc) · 9.3 KB
Raw

7. Application

This section describes how applications are designed and deployed.

Up to v0.3.0 of the current specification, the Application was known as ApplicationConfiguration.

Application

The Application entity defines a list of components that will be instantiated once the application is deployed.

Users will specify the final parametrization of each component and the traits that are applied to augment their functionality or alter their behavior. Additionally, a set of scopes grouping different subsets of components can be specified.

Top-Level Attributes

The top-level attributes of a application define its metadata, version, kind, and spec.

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/v1beta1 in this version of specification.
kind string Y Must be Application
metadata Metadata Y Information about the application.
spec Spec Y A specification for application attributes.

Spec

The specification of applications defines components to create, traits attached to each components, and a set of scopes the components drop in.

Attribute Type Required Default Value Description
components []Component Y Component specification.

Component

Attribute Type Required Default Value Description
name string Y The name of the component instance.
type string Y A reference to the component definition that will be instantiated by the application. Optionally a namespaced component may be referenced as <namespace>/<component_name>. 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, the concept of namespace matches the existing one in Kubernetes.
properties Properties Y A set of values assigned to the parameters exposed from the component schematic.
traits []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.

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.

Trait

Attribute Type Required Default Value Description
type string N A reference to the name of trait definition. For one type of trait, there could be only one configuration in one component.
properties Properties Y The properties values to use this trait.

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 will overwrite the component's parameters following schematic defined in component schematic.

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. 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 configurable elements of a component: its type, properties, traits, and scopes.

apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
  name: my-example-app
  annotations:
    version: v1.0.0
    description: "Brief description of the application"
spec:
  components:
    - 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:
        - type: scaler # scaler trait to specify the number of replicas for the backend component
          properties:
            replicas: 4
      scopes:
        "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 component definitions representing the web user interface and the backend of an imaginary application. Two traits 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 necessarily 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 runtime must be able to create any Trait entity that is registered on the system by means of a TraitDefinition.

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.

  • Each time a component is deployed, it must be deployed _with an application. 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.
  • When an instance is first created, it is in its initial revision state. Each time an upgrade operation occurs, we say that a new revision of that instance occurs. (There is, however, no assumption that there must be a corresponding revision object stored somewhere).

Releases

In Twelve-Factor Applications, a release is defined as a build plus a set of configs. That is, any change to either a build or configuration produces a new release. In the Open Application Model, the analog is that component, trait, and scope objects combined with an application jointly constitute a release.

For OAM applications, a release is defined thus:

A release is a named application, together with its description of correlated components, scopes, and traits.

In addition, as an application is released, its component instances_ are also released.

To accommodate this definition of a release, an OAM platform SHOULD make the following assumptions:

  • An application is mutable.
  • Any change to an application results (conceptually) in a new release that supersedes older releases.
    • If an application is updated, and the new version includes components not present in the original application, component instances MUST be created
    • If an application is updated, and the new version does not have a record of a component that the previous application contained, that component instance MUST be deleted
    • Traits similarly SHOULD be attached and detached according to the same guidelines
    • Components' relationships to Application Scopes SHOULD be applied or removed according to the same guidelines

Further Reading

For further details about a full workflow of application deployment, please check KubeVela's documentation.

Tables Next
6. Traits 8. Practical Considerations