README ¶
acbuild
acbuild is a command line utility to build and modify App Container Images (ACIs), the container image format defined in the App Container (appc) spec.
Rationale
Dockerfiles are powerful and feature useful concepts such as build layers, controlled build environment. At the same time, they lack flexibility (impossible to extend, re-use environment variables) and don't play nicely with the appc spec and Linux toolchain (e.g. shell, makefiles)
acbuild
is a command-line tool that natively supports ACI builds and integrates
well with shell, makefiles and
other Unix tools.
Installation
Runtime dependencies
acbuild requires a handful of commands be available on the system on which it's run:
systemd-nspawn
cp
mount
modprobe
gpg
Build from source
Currently the only way to install acbuild
is to build from source.
Follow these steps to do so:
-
Grab the source code for
acbuild
bygit clone
ing the source repository:cd ~ git clone git@github.com:appc/acbuild
-
Run the
build
script from the root source repository directory:cd acbuild ./build
Or, if you want to build in docker (assuming
$PWD
exists and containsacbuild/
on your Docker host):cd acbuild ./build-docker
-
A
bin/
directory will be created that contains theacbuild
tool. To make sure your shell can find this executable, append this directory to your environment's$PATH
variable. You can do this in your.bashrc
or similar file, for example:vi ~/.bashrc
and put the following lines at the end of the file:
export ACBUILD_BIN_DIR=~/acbuild/bin
export PATH=$PATH:$ACBUILD_BIN_DIR
Usage
A build with acbuild
is explicitly started with begin
and finished with
end
. While a build is in progress the current ACI is stored expanded in the
current working directory at .acbuild.tmp
. A build can be started with an
empty ACI, or an initial ACI can be provided.
The following commands are supported:
-
acbuild begin [ACI]
Begin a build. Optionally an ACI can be specified (either on the filesystem or fetched via meta discovery) as a starting point for the build. If unspecified, an empty ACI will be the starting point.
-
acbuild write ACI_PATH
Write an ACI resulting from the current build context to the given path. See the section below on signing ACIs.
-
acbuild end
End a build, deleting the current build context.
-
acbuild annotation add NAME VALUE
Updates the ACI to contain an annotation with the given name and value. If the annotation already exists, its value will be changed.
-
acbuild annotation remove NAME
Removes the annotation with the given name from the ACI.
-
acbuild dependency add IMAGE_NAME --image-id sha512-... --label env=canary
Updates the ACI to contain a dependency with the given name. If the dependency already exists, its values will be changed.
-
acbuild dependency remove IMAGE_NAME
Removes the dependency with the given image name from the ACI.
-
acbuild environment add NAME VALUE
Updates the ACI to contain an environment variable with the given name and value. If the variable already exists, its value will be changed.
-
acbuild environment remove NAME
Removes the environment variable with the given name from the ACI.
-
acbuild label add NAME VALUE
Updates the ACI to contain a label with the given name and value. If the label already exists, its value will be changed.
-
acbuild label remove NAME
Removes the label with the given name from the ACI.
-
acbuild mount add NAME PATH
Updates the ACI to contain a mount point with the given name and path. If the mount point already exists, its path will be changed.
-
acbuild mount remove NAME
Removes the mount point with the given name from the ACI.
-
acbuild port add NAME PROTOCOL PORT
Updates the ACI to contain a port with the given name, protocol, and port. If the port already exists, its values will be changed.
-
acbuild port remove NAME
Removes the port with the given name from the ACI.
-
acbuild copy PATH_ON_HOST PATH_IN_ACI
Copy a file or directory from the local filesystem into the ACI.
-
acbuild run CMD [ARGS]
Run a given command in the ACI.
-
acbuild set-name ACI_NAME
Changes the name of the ACI in its manifest.
-
acbuild set-group GROUP
Set the group the app will run as inside the container.
-
acbuild set-user USER
Set the user the app will run as inside the container
-
acbuild set-exec CMD [ARGS]
Sets the exec command in the ACI's manifest.
acbuild run
acbuild run
builds the root filesystem with any dependencies the ACI has
using overlayfs, and then executes the given command using systemd-nspawn. The
current ACI being built is the upper level in the overlayfs, and thus modified
files that came from the ACI's dependencies will be copied into the ACI. More
information on this behavior is available
here.
acbuild run
requires overlayfs if the ACI being operated upon has
dependencies.
acbuild run
also requires root.
Signing ACIs
When finishing a build with acbuild write
, if the --sign
flag is provided
acbuild will sign the resulting ACI by invoking the gpg
command on the
system. By default the --armor
and --yes
flags are passed to gpg
, but if
this is not sufficient any arguments given to acbuild end
after the ACI to
write are passed along to gpg
.
Some examples:
acbuild write --sign mynewapp.aci
acbuild write --sign mynewapp.aci -- --no-default-keyring --keyring ./rkt.gpg
Context-Free Mode
Calling begin
and end
with acbuild to make a single change to an existing
ACI can be cumbersome, so acbuild provides a context free mode. The
--modify=path/to/app.aci
flag can be used to specify an ACI to modify, and
when provided the current build context will be ignored and the change will be
applied to the given ACI instead.
Planned features
Squash
acbuild squash
: fetch all the dependencies for the given image and squash them
together into the ACI without dependencies.
Image pushing with write
When acbuild goes to write the ACI, meta discovery could be performed on the name that was set for the ACI to find an endpoint to push the image to, instead of saving the ACI on the local filesystem.
Alternate execution engine
Support multiple execution engines, notably runc.
Examples
Use apt-get to install nginx.
acbuild begin
acbuild dependency add quay.io/fermayo/ubuntu
acbuild run -- apt-get update
acbuild run -- apt-get -y install nginx
acbuild set-exec /usr/sbin/nginx
acbuild set-name example.com/ubuntu-nginx
acbuild write ubuntu-nginx.aci
acbuild end
Related work
- https://github.com/sgotti/baci
- https://github.com/appc/spec/tree/master/actool - particularly the
build
andpatch-manifest
subcommands.acbuild
may subsume such functionality, leavingactool
as a validator only. - https://github.com/blablacar/cnt
Directories ¶
Path | Synopsis |
---|---|
Godeps
|
|
_workspace/src/github.com/appc/spec/aci
Package aci contains various functions for working with App Container Images.
|
Package aci contains various functions for working with App Container Images. |
_workspace/src/github.com/appc/spec/discovery
Package discovery contains an experimental implementation of the Image Discovery section of the appc specification.
|
Package discovery contains an experimental implementation of the Image Discovery section of the appc specification. |
_workspace/src/github.com/appc/spec/pkg/tarheader
Package tarheader contains a simple abstraction to accurately create tar.Headers on different operating systems.
|
Package tarheader contains a simple abstraction to accurately create tar.Headers on different operating systems. |
_workspace/src/github.com/appc/spec/schema
Package schema provides definitions for the JSON schema of the different manifests in the App Container Specification.
|
Package schema provides definitions for the JSON schema of the different manifests in the App Container Specification. |
_workspace/src/github.com/appc/spec/schema/lastditch
Package lastditch provides fallback redefinitions of parts of schemas provided by schema package.
|
Package lastditch provides fallback redefinitions of parts of schemas provided by schema package. |
_workspace/src/github.com/appc/spec/schema/types
Package types contains structs representing the various types in the app container specification.
|
Package types contains structs representing the various types in the app container specification. |
_workspace/src/github.com/coreos/rkt/pkg/tar
Package tar contains helper functions for working with tar files
|
Package tar contains helper functions for working with tar files |
_workspace/src/github.com/spf13/cobra
Package cobra is a commander providing a simple interface to create powerful modern CLI interfaces.
|
Package cobra is a commander providing a simple interface to create powerful modern CLI interfaces. |
_workspace/src/github.com/spf13/pflag
pflag is a drop-in replacement for Go's flag package, implementing POSIX/GNU-style --flags.
|
pflag is a drop-in replacement for Go's flag package, implementing POSIX/GNU-style --flags. |
_workspace/src/github.com/syndtr/gocapability/capability
Package capability provides utilities for manipulating POSIX capabilities.
|
Package capability provides utilities for manipulating POSIX capabilities. |
_workspace/src/golang.org/x/crypto/ssh/terminal
Package terminal provides support functions for dealing with terminals, as commonly found on UNIX systems.
|
Package terminal provides support functions for dealing with terminals, as commonly found on UNIX systems. |
_workspace/src/golang.org/x/net/html
Package html implements an HTML5-compliant tokenizer and parser.
|
Package html implements an HTML5-compliant tokenizer and parser. |
_workspace/src/golang.org/x/net/html/atom
Package atom provides integer codes (also known as atoms) for a fixed set of frequently occurring HTML strings: tag names and attribute keys such as "p" and "id".
|
Package atom provides integer codes (also known as atoms) for a fixed set of frequently occurring HTML strings: tag names and attribute keys such as "p" and "id". |
_workspace/src/golang.org/x/net/html/charset
Package charset provides common text encodings for HTML documents.
|
Package charset provides common text encodings for HTML documents. |
_workspace/src/speter.net/go/exp/math/dec/inf
Package inf (type inf.Dec) implements "infinite-precision" decimal arithmetic.
|
Package inf (type inf.Dec) implements "infinite-precision" decimal arithmetic. |
The registry package exists to manage ACIs for acbuild.
|
The registry package exists to manage ACIs for acbuild. |