Skip to content

Latest commit

 

History

History
183 lines (127 loc) · 10.8 KB

7.application_configuration.md

File metadata and controls

183 lines (127 loc) · 10.8 KB
Raw

7. Application Configuration

Target Roles: Application Operator, Application Developer

This section describes how applications are deployed using application configurations.

A component can be deployed into any number of runtimes, any number of times. Each deployment of a component is called an instance. Each time a component is deployed, it must be deployed with a configuration. This section of the specification describes configurations.

An application configuration (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:

  • Information about the particular instance, such as:
    • Name
    • Release version
    • Description
  • Values for the defined parameters for a component, and for its respective components
  • Trait assignments to add operational functionality, together with any trait configuration

Instances and upgrades

An instance is a trackable deployment of an application configuration. A component instance is an instance of a component that is created during the deployment of an application configuration. It is created when a component is deployed together with a configuration. Each subsequent upgrade of a component will modify the given instance after the application configuration is redeployed. And each subsequent upgrade of an application configuration can modify any of the component instances controlled by that application configuration. 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.

When an instance is first created, it is in its initial release state. Each time an upgrade operation occurs, we say that a new release of that instance occurs. (There is, however, no assumption that there is a corresponding release 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 definitions combined with an application configuration jointly constitute a release.

For OAM applications, a release is defined thus:

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

In addition, as an application configuration is released, its component instances (running copies of a named component) are also released.

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

  • A component (as defined in the component model section) is mutable. Upgrade can happen by updating the component, e.g. updating image.
  • Any change to an application configuration results (conceptually) in a new release that supersedes older releases.
    • If an application configuration is updated, and the new version includes components not present in the original application configuration, component instances MUST be created
    • If an application configuration is updated, and the new version does not have a record of a component that the previous application configuration 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

Runtime and Application Configuration

The Workload chapter of the specification defines how schematics are constructed. The resulting schematics may then be used to instantiate a component on a OAM-compliant runtime.

A component can be deployed into numerous different runtimes. However, at runtime there is a one-to-one correspondence between an instance of a configuration and an application configuration.

Conceptually speaking, an application configuration is managed as part of the application operator role. An application configuration references one or more component instances, each represented by a section that defines how an instance of a component spec should be deployed. In detail, this section has three parts:

  • Overrides of component parameters
  • List of traits, each of which has overrides for that trait's parameters
  • List of application scopes into which the component should be deployed

Defining an application configuration

Top-Level Attributes

The top-level attributes of a application configuration 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/v1alpha2 in this version of specification.
kind string Y Must be ApplicationConfiguration
metadata Metadata Y Information about the application configuration.
spec Spec Y A specification for application configuration attributes.

Spec

The specification defines parameters that can be overridden at deployment time, and a set of scopes and component instances to create.

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

Component

This section defines the instances of components to create with the application configuration.

Attribute Type Required Default Value Description
componentName string N The name of the component of which to create an instance. The revision of this instance will always reflect the latest change of the component (i.e. always track latest revision). This is mutually exclusive with revisionName.
revisionName string N The name of specific component revision of which to create an instance, i.e. always stick to specific revision until this field is updated. This is mutually exclusive with componentName.
parameterValues []ParameterValue N Overrides of parameters that are exposed by the application scope type defined in type.
scopes []Scope N The scopes to be used in the component. A component joins a scope by referencing it.
traits []Trait N The traits to attach to this component instance.

In addition to being unique, the componentName must follow these naming rules:

The componentName 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.

Scope

The scope section defines the scope into which the component should be deployed.

Attribute Type Required Default Value Description
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

The trait section defines an instance of a trait.

Attribute Type Required Default Value Description
trait TraitData N Information required by a trait definition.

TraitData

The TraitData section contains the instantiation of the schema referenced by the corresponding traitDefinition. The schema can be used to validated this section.

It is RECOMMENDED that apiVersion and kind are specified, for example:

- trait:
    apiVersion: core.oam.dev/v1alpha2
    kind: ManualScalerTrait
    spec:
      replica: 2

ParameterValue

Values supplied to parameters that are used to override the parameters exposed by other types.

Attribute Type Required Default Value Description
name string Y The name of the component parameter for which to provide a value.
value string Y The value of the parameter.

A name consists of any Unicode letter or numeric character, and also _ (underscore), - (en dash), and . (period). A value contains any sequence of printable Unicode characters.

Example

The following is an example of a complete YAML file that expresses configuration and traits. This example illustrates the four configurational elements of a component: its name, parameter values, traits, and scopes.

apiVersion: core.oam.dev/v1alpha2
kind: ApplicationConfiguration
metadata:
  name: my-app-deployment
  annotations:
    version: v1.0.0
    description: "Description of this deployment"
spec:
  components:
    - componentName: my-web-app-component
      parameterValues:
        - name: PARAMETER_NAME
          value: SUPPLIED_VALUE
        - name: ANOTHER_PARAMETER
          value: "AnotherValue"
      traits:
        - name: manualscaler.core.oam.dev
          version: v1
          spec:
            replicaCount: 3
      scopes:
        - scopeRef:
            apiVersion: core.oam.dev/v1alpha2
            kind: NetworkScope
            name: example-vpc-network

The example above illustrates a complete application configuration, including its scopes, component instances and their traits, and parameter overrides which can be specified from the command line at the time of deployment.

For further details, see this example workflow.

Tables Next
6. Traits 8. Practical Considerations