Skip to main content Link Search Menu Expand Document (external link)

Changes with OAM 0.3.1

We are glad to announce that in the coming days, the NAPPTIVE platform will roll out support for the newer release of the Open Application Model specification (v.0.3.1). We have been working actively during the past months to make sure that the new specification, its runtime, and the overall user experience match our vision. We have supported OAM since our inception, as we believe it to be key to enabling simple yet robust application delivery.

New features

  • Helm

The new release will introduce support to define application components based on a Helm chart.

Example of a Helm component
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
  name: app-with-helm-component
spec:
  components:
    - name: compname
      type: helm
      properties:
        repoType: "helm"
        url: "https://<chart_url>/"
        chart: "<chart_name>"
        version: "<chart_version>"
        values:
          key1:
            key11:
              key111: <value>
  • Workflows

The new Application entity supports specifying the workflow that needs to be used to deploy the application. This is the first step toward a fully customizable deployment pipeline.

Example workflow to deploy and send a Slack notification
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
  name: slack-app
spec:
  components:
  - name: slack-app-comp
    type: worker
    properties:
        image: my-app-image:v1.0.0
  workflow:
    steps:
      - name: apply-app
        type: apply-application 
      - name: slack-message
        type: notification
        properties:
          slack: 
            # the Slack webhook address, please refer to: https://api.slack.com/messaging/webhooks
            url:
              ...

What changes?

The newer Open Application Model addresses some of the issues that the community has found during the past year. In particular, the high-level entities (ApplicationConfiguration, ComponentDefinition, etc.) have been revisited with the intent of further simplifying their use. The following diagram describes the high-level changes:

New application

While the concepts of Component and Trait still remain, their day-to-day utilization has been improved. The system provides a set of existing ready-to-use ComponentDefinitions that can be used as a template in such a way that a new application will only need to set the parameters in the Application file itself.

Naming

Some of the naming conventions have been updated. For example, “parameters”, “params”, and equivalent terms have now been consolidated as properties throughout the different entities.

ApplicationsConfiguration

The ApplicationConfiguration entity has been renamed as Application. The purpose of this entity remains the same as it defines the components that are part of the application, their components, the traits that augment their functionality, and now it also adds support for an application-level workflow that will customize the way the application is deployed.

The following examples illustrate the before-and-after for some of the most well known applications in our catalog:

Before: Drawio with OAM 0.2.1
apiVersion: core.oam.dev/v1alpha2
kind: ApplicationConfiguration
metadata:
  name: drawio
  annotations:
    version: 17.2.4
    description: "draw.io (formerly Diagramly) is free online diagram software"
spec:
  components:
    - componentName: drawio
      traits:
        - trait:
            apiVersion: core.napptive.com/v1alpha1
            kind: Ingress
            metadata:
              name: drawio-ingress
            spec:
              name: drawio
              protocol: HTTP
              port: 8080
              path: /
              rewritePath: /

After: Drawio with OAM 0.3.1
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
  name: drawio
  annotations:
    version: 17.2.4
    description: "draw.io (formerly Diagramly) is free online diagram software"
spec:
  components:
    - name: drawio
      type: webservice
      properties:
        image: jgraph/drawio:17.2.4
        ports:
          - port: 8080
            expose: true
          - port: 8443
            expose: false
      traits:
        - type: napptive-ingress         
          properties:
            name: drawio-ingress
            port: 8080
            path: /

ComponentDefinitions

Components are a fundamental entity when defining an application. With OAM 0.2.1 it was necessary to create a ComponentDefinition for each of the components that were part of the application. As doing this represents a significant amount of extra-work, with OAM 0.3.1 the platform will automatically offer a set of components that will work as an instantiation template.

In other words, it is likely that for most use cases, reusing the system components will be enough to deploy the most common types of applications avoiding the need to write your own component definitions. The platform will still provide support for custom component definitions that will be associated with a particular environment.

As an example, to launch a simple application such as nginx, it will be enough to write an application specification as:

apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
  name: nginx-app
spec:
  components:
    - name: nginx
      type: webservice
      properties:
        image: nginx:1.20.0
        ports:
        - port: 80
          expose: true

By default the following component types will be available:

Type Description
webservice Describes long-running, scalable, containerized services that have a stable network endpoint to receive external network traffic from customers.
worker Describes long-running, scalable, containerized services that running at backend. They do NOT have network endpoint to receive external network traffic.
statefulservice A long-running, scalable application with guarantees about the ordering and uniqueness of the replicas.
k8s-objects K8s-objects allow users to specify raw K8s objects in properties
task Describes jobs that run code or a script to completion.
cron-task Describes cron jobs that run code or a script to completion.

Additionally, components can also be defined using CUE lang so that customization and special behaviors do not require writing your own Kubernetes operator.

Traits

Traits remain the preferred option to customize a component adding or altering the functionality. In terms of referencing a trait, the syntax has been reduced as illustrated by the following examples:

Before: Using an ingress trait with OAM 0.2.1
# Nginx application
apiVersion: core.oam.dev/v1alpha2
kind: ApplicationConfiguration
metadata:
  name: nginx-app
spec:
  components:
    - componentName: nginx
      traits:
        - trait:
            apiVersion: core.napptive.com/v1alpha1
            kind: Ingress
            metadata:
              name: nginx-ingress
            spec:
              name: nginx
              protocol: HTTP
              port: 80
              path: /
              rewritePath: /
After: Using an ingress trait with OAM 0.3.1
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
  name: nginx-app
spec:
  components:
    - name: nginx
      type: webservice
      properties:
        image: nginx:1.20.0
        ports:
        - port: 80
          expose: true
      traits:
      - type: napptive-ingress # Select the type of trait
        properties: # Set the parameters
          name: nginx-ingress
          port: 80
          path: /

Scopes

The usage of Scopes and ScopeDefinitions in OAM 0.2.1 resulted in a low adoption due to its complexity and the extra requirements around tooling and operators to exploit their full potential.

With the release of OAM, a new entity called Policy has been introduced with the aim of providing the same flexibility and customization options as traits, but instead of being applied to a particular component, the Policy will apply to the whole application.

The following snippet shows an example of the previous HealthScope reimplemented with a Policy.

Using policies OAM 0.3.1
apiVersion: core.oam.dev/v1beta1
kind: Application
metadata:
  name: app-with-healthscope
spec:
  components:
    - name: component1
      type: worker
      properties:
        image: my-app-image:v1.0.0
  policies:
    - name: healthscope-policy # policy name
      type: health # set to health
      properties:
        probeInterval: 30 # (Required) health checking interval, 30s by default
        probeTimeout: 10 # (Required) health checking timeout, 10s by default

FAQ

What would happen to the applications in the catalog?

The NAPPTIVE team will automatically update your existing applications in the catalog so you do not need to worry about the migration process of those.

What would happen to my running applications?

With the introduction of OAM 0.3.1, entity support for OAM 0.2.1 will unfortunately no longer be available due to technical incompatibilities requiring all applications to be migrated to the new specification. We expect that this is the last time such incompatibilities require such drastic measures. During the migration process, all existing applications will be shut down and removed from the environments, so we encourage you to backup all existing data so you can safely redeploy your updated applications.

Migration support

If you need help migrating any of your applications from OAM 0.2.1 to OAM 0.3.1, just reach out through Slack. We will provide one-on-one support to help you migrate your applications. Applications in the catalog will be updated automatically.