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

Examples

For a list of examples that conform to the spec, check out github.com/projectatomic/nulecule-library.

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.
params	[ ParamsObject ]	Optional A list of ParamsObject that contain provider specific 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, then it is an external Atomic App 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