application-configuration.md

Application Configuration

An application configuration is a resource that declares how an application is to be instantiated and configured, including parameter overrides and add-on traits. The application configuration .yaml file represents a logical grouping of one or more components, their operational characteristics, and runtime configuration. It is used to deploy (and update) instances of these constituent components.

The application configuration is managed as part of the application operator role.

The key parts of an application configuration include:

• Metadata: Information about the installed application configuration.
• Variables: (Optional). Variables for common parameter values across multiple components.
• Components: The constituent microservices of the application and their runtime configuration.
• Traits: (Optional). A list of traits to enable for a given component.
• Scopes: (Optional). A list of scopes to apply to a given component.

Here's an example application configuration (.yaml file):

apiVersion: core.oam.dev/v1alpha1
kind: ApplicationConfiguration
metadata:
  name: first-app
spec:
  variables:
  - name: SECTION_NUMBER
    value: 3
  components:
  - componentName: nginx-component
    instanceName: first-app-nginx
    parameterValues:
    - name: poet
      value: Eliot
    - name: poem
      value: The Wasteland
    - name: section
      value: "[fromVariable(SECTION_NUMBER)]"
    traits:
    - name: ingress
      properties:
        hostname: example.com
        path: /
        servicePort: 80
    applicationScopes:
      - my-health-scope

To create an application configuration, you'll first need to author the component schematics that will constitute your application. From there, you might want to start with a template like the one above (or in the provided examples) and customize to your needs.

Common operations

Here are the key operations for installing and managing application configurations.

Install an application configuration:

$ kubectl apply -f <application-configuration>.yaml

List application configurations:

$ kubectl get configurations

List details of a specific configuration:

$ kubectl get configuration <app-config-name> -o yaml

Delete a configuration:

$ kubectl delete configuration <app-config-name>

The remaining sections will walk you through the key aspects and options of an application configuration.

Metadata

The metadata section provides information about the object represented by this schematic (in this case, the ApplicationConfiguration), including its name, and optionally, any labels or annotations in the form of key/value pairs.

The metadata section consists of the following fields:

Name	Description	Allowable values	Required	Default
name	The identifier you'll use to manage your application configuration with kubectl (designated as <app-config-name> in the commands above).	string	☑
labels	A set of string key/value pairs assigned to the application configuration.	Use OAM/Kubernetes label format.
annotations	Further metadata in key/value format describing the application configuration, such as version and description.	Use OAM/Kubernetes label format. version and description are pre-defined in OAM and considered best practices.

Here's an example of how to specify a label and annotations:

# Example label and annotations in application config
metadata:
  name: custom-app
  labels:
    release: canary
  annotations:
    version: v1.0.0
    description: "Customized version of app"

Variables

The variables section provides a way for an application operator to specify common values that can be substituted into multiple other locations of the application configuration.

Name	Description	Allowable values	Required	Default
name	Name of the variable.	string. Must be unique per configuration. Includes Unicode letters, numeric characters, _, -, and .	☑
value	Value of the variable.	string. Any sequence of printable Unicode characters.	☑

To declare a variable, simply provide its name and value, then reference it using [fromVariable(<name>)] syntax as needed within your component parameterValues:

# Example variable declaration/reference in application config
variables:
- name: SECTION_NUMBER
  value: 3
components:
- componentName: custom-component
  instanceName: first-component
  parameterValues:
  - name: section
    value: "[fromVariable(SECTION_NUMBER)]"

Components

The components section defines the instances of components to create with the application.

An application configuration requires one or more listed components, each consisting of the following fields:

Name	Description	Allowable values	Required	Default
componentName	Name of the ComponentSchematic used to create this component instance.	string	☑
instanceName	The name for this runtime instance of the component.	string	☑
parameterValues	Values supplied to override parameters exposed in the ComponentSchematic.	Depends on available parameters of the component spec.
traits	Additional workload functionality to attach to the component instance.	See traits documentation.

Here's an example component definition:

# Example component definition in application config
components:
- componentName: helloworld-python-v1
  instanceName: first-app-helloworld-python-v1
  parameterValues:
  - name: target
    value: Rudr
  - name: port
    value: '9999'
  traits:
    - name: ingress
      properties:
        hostname: example.com
        path: /
        servicePort: 9999

Traits

For each of your components, you can optionally define one or more traits. A trait represents a piece of add-on functionality that attaches to a component workload, such as traffic routing rules or auto-scaling policies.

See the Traits topic guide for more on assigning and managing traits.

Here's an example of an entry to the traits section:

# Example trait entry

traits:
  - name: ingress
    properties:
      hostname: example.com
      path: /
      servicePort: 9999

Scopes

You can deploy one or more of your components within one or more application scopes. A scope represents a logical grouping of components based on common behaviors or dependencies. For example, you might group several component workloads under the same health scope in order to easily probe their aggregate health status, or you might group components together under a common network scope to link them to a particular network.

See the Scopes topic guide for more on configuring and applying scopes.

Here's an example of assigning a pre-configured scope (my-health-scope) to a given component within the application configuration:

# Example scope assignment
applicationScopes:
  - my-health-scope