Container Application Specification

NOTE: This is a work in progress effort that is expected to change quickly. Feel free to join the initiative!

Version 0.0.2

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in RFC 2119.

The Container Application Specification is licensed under GNU Free Documentation License Version 1.3, 3 November 2008.

Introduction

The Container Application specification is a project to describe ‘an Application’ that is composed of a set of dependent Container Applications (containerapp). The Container Application specification defines a set of files required to describe such a containerapp. These files can then be used by other tools to deploy a containerapp. Developers may use other tools to generate most of the required containerapp files. Additional utilities can also take advantage of the resulting files, such as testing tools.

Versioning

Within this specification we follow the semantic versioning pattern.

Revision History

Version Date Notes
0.0.2 2015-05-07 close issue #35 the graph is now a list of named items
0.0.1-alpha 2015-mm-dd TBD
v1-alpha 2015-04-10 reversioned to 0.0.1-alpha

Specification

Format

The files describing a containerapp in accordance with the Container Application Specification are represented using YAML 1.2 or JSON.

All field names in the specification are case sensitive.

By convention, the containerapp definition file is named Nulecule. The Nulecule is the primary file defining the containerapp and it’s relationship to dependencies.

Data Types

Primitive data types in the Container Application Specification are based on the types supported by the JSON-Schema Draft 4.

The formats defined by the Container Application Specification are:

Common Name type format Comments
integer integer int32 signed 64 bits
float number float
string string
byte string byte
boolean boolean
date string date As defined by full-date - RFC3339
dateTime string date-time As defined by date-time - RFC3339
password string password Used to hint UIs the input needs to be obscured.
URL URL URL As defined by URL - RFC3986 Section 1.1.3

Terminology

Container Application

Provider

Schema

Container Application Object

This is the root object for the specification.

Fields
Field Name Type Description
id string Required. The machine readable id of the Container Application.
specversion string Required. The semantic version string of the Container Application Specification used to describe the app. The value MUST be "0.0.2".
metadata [ MetadataObject ] Optional An object holding optional metadata related to the Container Application, this may include license information or human readable information.
graph [ GraphObject ] Required. A list of depending containerapps. Strings may either match a local sub directory or another containerapp-spec compliant containerapp image that can be pulled via a provider.
requirements [ RequirementsObject ] Optional A list of requirements of this containerapp.

Metadata Object

Metadata for the Container Application.

Fields
Field Name Type Description
name string Optional A human readable name of the containerapp.
appversion string Optional The semantic version string of the Container Application.
description string Optional A human readable description of the Container Application. This may contain information for the deployer of the containerapp.
license License Object Optional The license information for the containerapp.
arbitrary_data string Optional Arbitrary key: value pair(s) of metadata. May contain nested objects.
Metadata Object Example:
name: myapp
appversion: 1.0.0
description: description of myapp
foo: bar
othermetadata:
  foo: bar
  files: file://path/to/local/file
{
  "name": "myapp",
  "appversion": "1.0.0",
  "description": "description of myapp",
  "foo": "bar",
  "othermetadata": {
    "foo": "bar",
    "files": "file://path/to/local/file"
  }
}

License Object

License information for the Container Application.

Fields
Field Name Type Description
name string Required. The human readable license name used for the Container Application, no format imposed.
url string Optional A URL to the license used for the API. MUST be in the format of a URL.
License Object Example:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
{
  "name": "GNU GPL, Version 3",
  "url": "https://www.gnu.org/copyleft/gpl.html"
}

Graph Object

The graph is a list of items (containerapps) the Container Application depends on.

Fields of a Graph Item Object
Field Name Type Description
name string Required. The name of the depending Container Application.
source URL Optional Source location of the Container Application, the source MUST be specified by a valid URL. If source is present, all other fields SHALL be ignored.
params [ ParamsObject ] Optional A list of ParamsObject that contain provider specific information. If params is present, source field SHALL be ignored.
artifacts [ ArtifactsObject ] Optional A list of ArtifactsObject that contain providr specific information. If artifacts is present, source field SHALL be ignored.
Graph Item Object Example:
---
name: atomicapp-zabbix-mongodb
source: uri://registry.devops.example.com
# if no "artifacts" is specified, than it is an external Atomicapp to be pulled 
# and installed from the specified source
{
"name": "atomicapp-zabbix-mongodb"
"source": "uri://registry.devops.example.com"
}

Parameters Object

A list of Parameters the containerapp requires, has set some defaults for or needs user input.

Fields
Field Name Type Description
name string Required. The name of the parameter.
description string Required. A human readable description of the parameter.
constraints ConstraintObject Optional An optional definition of constraints to the parameter.
default string Optional An optional default value for the parameter.
hidden string Optional An optional boolean signifying the parameter should be obscured when displayed.
Parameters Object Example:
name: password
description: mongoDB Admin password
hidden: true
constraints: 
  - allowed_pattern: "[A-Z0-9]+"
    description: Must consist of characters and numbers only.
{
  "name": "password",
  "description": "mongoDB Admin password",
  "hidden": true
  "constraints": [
    {
      "allowed_pattern": "[A-Z0-9]+",
      "description": "Must consist of characters and numbers only."
    }
  ]
}

Constraint Object

Constraints to the parameter.

Fields
Field Name Type Description
allowed_pattern string Required. A regexp declaring the allowed pattern.
description string Required. A human readable description of the parameter.

Requirements Object

The list of requirements of the Container Application. It may be Storage Requirement Objects (for a persistent Volume).

Storage Requirements Object

This describes a requirement for persistent, read-only or read-write storage that should be available to the containerapp on runtime. The name of this object MUST be "persistentVolume".

Fields of Storage Requirement
Field Name Type Description
name string Required. A name associated with the storage requirement.
accessModes string Required. May be "ReadWrite" or "ReadOnly".
size integer Required. Size of required the storage.
Storage Requirement Example:
---
- persistentVolume:
    name: "var-lib-mongodb-data"
    accessMode: "ReadWrite"
    size: 4 # GB by default
  {
    "persistentVolume": {
      "name": "var-lib-mongodb-data",
      "accessMode": "ReadWrite",
      "size": 4
    }
  }

Artifacts Object

The Artifacts Object describes a list of provider specific artifact items. These artifact items will be used during installation of the containerapp to deploy it to the provider. Each provider key contains a list of artifacts. Each artifact list item is either a URL string or a source control repository object.

  • URL: must be a URL string prepended by URI type such as http://, https://, file: (relative path) or file:// (absolute path). URI type file: may be a single file or a directory path to multiple files. Directories must end with a trailing slash such as file:relative/path/to/multiple/artifact/files/.
  • SourceControlRepositoryObject
Artifacts Example:
---
artifacts: # list of local or remote files or remote repository path to be processed by the provider selected at install-time
  kubernetes:
    - source: https://github.com/aweiteka/kube-files.git
      tag: release-1
  openshift:
    - file:relative/path/openshift/artifacts/
    - https://example.com/openshift/strategies.json
    - inherit:
      - kubernetes
{
  "artifacts": {
    "kubernetes": [
      {
        "source": "https://github.com/aweiteka/kube-files.git",
        "path": "/artifacts/kubernetes/,
        "tag": "release-1"
      }
    ],
    "openshift": [
      "file:relative/path/openshift/artifacts/",
      "https://example.com/openshift/strategies.json",
      {
        "inherit": [
          "kubernetes"
        ]
      }
    ]
  }
}

Source Control Repository Object

Source Control Repository Object for artifact sources.

Fields of a Source Control Repository Object
Field Name Type Description
source URL Required Source location of the source control repository. The source MUST be specified by a valid URL.
path string Optional The path to a specific artifact file or directory of artifact files. Default value is / which would reference all of the files in the repository.
type string Optional The source control type. Default value is git.
branch string Optional The source control branch. Default value is master.
tag string Optional The source control tag.

Directory Layout

Names of files that must be present are contained in the file files in the root directory of the specification. These filenames support globbing.

A filesystem layout of a typical app is this: ├── Nulecule ├── Dockerfile ├── <provider_files_dir> │ ├── ... │ └── <provider_files> └── README.md

  • Nulecule: Container Application definition
  • Dockerfile: standard packaging for this containerapp
  • <provider_files_dir>: directories of provider-specific files referenced in a containerapp definition file
    • PROVIDER_FILES: provider-specific files necessary for deploying to provider
  • README.md: information for deploying this application

README.md

The README.md is the human-readable document. It describes the containerapp in enough detail so an operator can make parameterization and other deployment decisions.

NOTE: This is optional. It is possible for some applications to be self-describing through well-written descriptions and input validation.

Good Practices

An implementation of the Nulecule Specification should declare what providers it supports. This should be done by adding a Label to the container image, by adding a line to the Dockerfile: LABEL io.projectatomic.nulecule.providers = "kubernetes,docker,openshift"

Conventions

A few conventions are used in the context of Container Applications.

Parameters for Providers

Each provider in the ArtifactsObject of the GraphObject may correspond to a containerapp level ParamsObject.

Version Label

The Dockerfile must carry a Label declaring the version of the specification that is used: LABEL io.projectatomic.nulecule.specversion 0.0.2