<img src="https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Achtung.svg/2000px-Achtung.svg.png" alt="WARNING" width="25" height="25"> Disclaimer <img src="https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Achtung.svg/2000px-Achtung.svg.png" alt="WARNING" width="25" height="25">

With the formation of the Open Container Initiative (OCI), the industry has come together in a single location to define specifications around applications containers. OCI is intended to incorporate the best elements of existing container efforts like appc, and several of the appc maintainers are participating in OCI projects as maintainers and on the Technical Oversight Board (TOB). Accordingly, as of late 2016, appc is no longer being actively developed, other than minor tweaks to support existing implementations.

It is highly encouraged that parties interested in container specifications join the OCI community.

The App Container Image format (ACI) maps more or less directly to the OCI Image Format Specification, with the exception of signing and dependencies.
The App Container Executor (ACE) specification is related conceptually to the OCI Runtime Specification, with the notable distinctions that the latter does not support pods and generally operates at a lower level of specification.
App Container Image Discovery does not yet have an equivalent specification in the OCI project (although it has been discussed and proposed)

For more information, see the OCI FAQ and a more recent CoreOS blog post announcing the OCI Image Format.

App Container

appc logo

This repository contains schema definitions and tools for the App Container (appc) specification. These include technical details on how an appc image is downloaded over a network, cryptographically verified, and executed on a host. See SPEC.md for details of the specification itself.

For information on the packages in the repository, see their respective godocs.

What is the App Container spec?

App Container (appc) is a well-specified and community developed specification for application containers. appc defines several independent but composable aspects involved in running application containers, including an image format, runtime environment, and discovery mechanism for application containers.

What is an application container?

An application container is a way of packaging and executing processes on a computer system that isolates the application from the underlying host operating system. For example, a Python web app packaged as a container would bring its own copy of a Python runtime, shared libraries, and application code, and would not share those packages with the host.

Application containers are useful because they put developers in full control of the exact versions of software dependencies for their applications. This reduces surprises that can arise because of discrepancies between different environments (like development, test, and production), while freeing the underlying OS from worrying about shipping software specific to the applications it will run. This decoupling of concerns increases the ability for the OS and application to be serviced for updates and security patches.

For these reasons we want the world to run containers, a world where your application can be packaged once, and run in the environment you choose.

The App Container (appc) spec aims to have the following properties:

Composable. All tools for downloading, installing, and running containers should be well integrated, but independent and composable.
Secure. Isolation should be pluggable, and the cryptographic primitives for strong trust, image auditing and application identity should exist from day one.
Decentralized. Discovery of container images should be simple and facilitate a federated namespace and distributed retrieval. This opens the possibility of alternative protocols, such as BitTorrent, and deployments to private environments without the requirement of a registry.
Open. The format and runtime should be well-specified and developed by a community. We want independent implementations of tools to be able to run the same container consistently.

What is the promise of the App Container Spec?

By explicitly defining - separate of any particular implementation - how an app is packaged into an App Container Image (ACI), downloaded over a network, and executed as a container, we hope to enable a community of engineers to build tooling around the fundamental building block of a container. Some examples of build systems and tools that have been built so far include:

goaci - ACI builder for Go projects
docker2aci - ACI builder from Docker images
deb2aci - ACI builder from Debian packages
actool - Simple tool to assemble ACIs from root filesystems
acbuild - A versatile tool for building and manipulating ACIs
dgr - A command-line utility to build ACIs and configure them at runtime
baci - A generic ACI build project
openwrt-aci - A tool to build ACIs based on OpenWRT snapshots
oci2aci - ACI builder from OCI bundle
nix2aci - ACI builder that leverages the Nix package manager and acbuild

What are some implementations of the spec?

The most mature implementations of the spec are under active development:

Jetpack - FreeBSD/Go
Kurma - Linux/Go
rkt - Linux/Go

There are several other partial implementations of the spec at different stages of development:

libappc - C++ library
Nose Cone - Linux/C++

Who controls the spec?

App Container is an open-source, community-driven project, developed under the Apache 2.0 license. For information on governance and contribution policies, see POLICY

Working with the spec

Building ACIs

Various tools listed above can be used to build ACIs from existing images or based on other sources.

As an example of building an ACI from scratch, actool can be used to build an Application Container Image from an Image Layout - that is, from an Image Manifest and an application root filesystem (rootfs).

For example, to build a simple ACI (in this case consisting of a single binary), one could do the following:

$ find /tmp/my-app/
/tmp/my-app/
/tmp/my-app/manifest
/tmp/my-app/rootfs
/tmp/my-app/rootfs/bin
/tmp/my-app/rootfs/bin/my-app
$ cat /tmp/my-app/manifest
{
    "acKind": "ImageManifest",
    "acVersion": "0.8.11",
    "name": "my-app",
    "labels": [
        {"name": "os", "value": "linux"},
        {"name": "arch", "value": "amd64"}
    ],
    "app": {
        "exec": [
            "/bin/my-app"
        ],
        "user": "0",
        "group": "0"
    }
}
$ actool build /tmp/my-app/ /tmp/my-app.aci

Since an ACI is simply an (optionally compressed) tar file, we can inspect the created file with simple tools:

$ tar tvf /tmp/my-app.aci
drwxrwxr-x 1000/1000         0 2014-12-10 10:33 rootfs
drwxrwxr-x 1000/1000         0 2014-12-10 10:36 rootfs/bin
-rwxrwxr-x 1000/1000   5988728 2014-12-10 10:34 rootfs/bin/my-app
-rw-r--r-- root/root       332 2014-12-10 20:40 manifest

and verify that the manifest was embedded appropriately

$ tar xf /tmp/my-app.aci manifest -O | python -m json.tool
{
    "acKind": "ImageManifest",
    "acVersion": "0.8.11",
    "annotations": null,
    "app": {
        "environment": [],
        "eventHandlers": null,
        "exec": [
            "/bin/my-app"
        ],
        "group": "0",
        "isolators": null,
        "mountPoints": null,
        "ports": null,
        "user": "0"
    },
    "dependencies": null,
    "labels": [
        {
            "name": "os",
            "value": "linux"
        },
        {
            "name": "arch",
            "value": "amd64"
        }
    ],
    "name": "my-app",
    "pathWhitelist": null
}

Validating App Container implementations

actool validate can be used by implementations of the App Container Specification to check that files they produce conform to the expectations.

Validating Image Manifests and Pod Manifests

To validate one of the two manifest types in the specification, simply run actool validate against the file.

$ actool validate ./image.json
$ echo $?
0

Multiple arguments are supported, and more output can be enabled with -debug:

$ actool -debug validate image1.json image2.json
image1.json: valid ImageManifest
image2.json: valid ImageManifest

actool will automatically determine which type of manifest it is checking (by using the acKind field common to all manifests), so there is no need to specify which type of manifest is being validated:

$ actool -debug validate /tmp/my_container
/tmp/my_container: valid PodManifest

If a manifest fails validat

Spec

Install / Use

README