Name	Name	Last commit message	Last commit date
parent directory ..
examples/template	examples/template
requirements	requirements
README.md	README.md
constraint.json	constraint.json
files	files
graph.json	graph.json
license.json	license.json
metadata.json	metadata.json
param.json	param.json
provider.json	provider.json
requirement.json	requirement.json
schema.json	schema.json

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, 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

Files

spec

Directory actions

More options

Directory actions

More options

Latest commit

History

spec

Folders and files

parent directory

README.md

Container Application Specification

Version 0.0.2

Introduction

Versioning

Revision History

Specification

Format

Data Types

Terminology

Schema

Container Application Object

Fields

Metadata Object

Fields

Metadata Object Example:

License Object

Fields

License Object Example:

Graph Object

Fields of a Graph Item Object

Graph Item Object Example:

Parameters Object

Fields

Parameters Object Example:

Constraint Object

Fields

Requirements Object

Storage Requirements Object

Fields of Storage Requirement

Storage Requirement Example:

Artifacts Object

Artifacts Example:

Source Control Repository Object

Fields of a Source Control Repository Object

Directory Layout

README.md

Good Practices

Conventions

Parameters for Providers

Version Label