Merge pull request #2571 from ijc/linuxkit-pkg

Implement package build, push and show-tag in linuxkit tool

docs/packages.md

@@ -11,6 +11,22 @@ All LinuxKit packages are:
 - Derived from well-known (and signed) sources for repeatable builds.
 - Build with multi-stage builds to minimise their size.
 
+## Package source
+
+A package source consists of a directory containing at least two files:
+
+- `build.yml`: contains metadata associated with the package
+- `Dockerfile`: contains the steps to build the package.
+
+`build.yml` contains the following fields:
+
+- `image` _(string)_: *(mandatory)* The name of the image to build
+- `org` _(string)_: The hub/registry organisation to which this package belongs
+- `arches` _(list of string)_: The architectures which this package should be built for (valid entries are `GOARCH` names)
+- `gitrepo` _(string)_: The git repository where the package source is kept.
+- `network` _(bool)_: Allow network access during the package build (default: no)
+- `disable-content-trust` _(bool)_: Disable Docker content trust for this package (default: no)
+- `disable-cache` _(bool)_: Disable build cache for this package (default: no)
 
 ## Building packages
 
@@ -24,6 +40,7 @@ Before you can build packages you need:
   bin/manifest-tool`, or `go get github.com:estesp/manifest-tool`, or
   via the LinuxKit homebrew tap with `brew install --HEAD
   manifest-tool`. `manifest-tool` must be in your path.
+- The LinuxKit tool `linuxkit` which must be in your path.
 
 Further, when building packages you need to be logged into hub with
 `docker login` as some of the tooling extracts your hub credentials
@@ -43,9 +60,13 @@ they can't be build in parallel.
 To build a package on an architecture:
 
 ```
-DOCKER_CONTENT_TRUST_REPOSITORY_PASSPHRASE="<passphrase>" make
+DOCKER_CONTENT_TRUST_REPOSITORY_PASSPHRASE="<passphrase>" linuxkit pkg push «path-to-package»
 ```
 
+`«path-to-package»` is the path to the package's source directory
+(containing at least `build.yml` and `Dockerfile`). It can be `.` if
+the package is in the current directory.
+
 **Note:** You *must* be logged into hub (`docker login`) and the
 passphrase for the key *must* be supplied as an environment
 variable. The build process has to resort to using `expect` to drive
@@ -68,10 +89,10 @@ architecture. The YAML files should consume the package as:
 Since it is not very good to have your passphrase in the clear (or
 even stashed in your shell history), we recommend using a password
 manager with a CLI interface, such as LastPass or `pass`. You can then
-invoke `make` like this (for LastPass):
+invoke the build like this (for LastPass):
 
 ```
-DOCKER_CONTENT_TRUST_REPOSITORY_PASSPHRASE=$(lpass show <key> --password) make
+DOCKER_CONTENT_TRUST_REPOSITORY_PASSPHRASE=$(lpass show <key> --password) linuxkit pkg push «path-to-package»
 ```
 
 ### Build packages as a developer
@@ -81,7 +102,7 @@ override the hub organisation used. You may also want to disable
 signing while developing. A typical example would be:
 
 ```
-make ORG=wombat NOTRUST=1 tag
+linuxkit pkg build -org=wombat -disable-content-trust «path-to-package»
 ```
 
 This will create a local image: `wombat/<image>:<hash>-<arch>` which
@@ -90,7 +111,7 @@ on other systems you can push the image to your hub account and pull
 from a different system by issuing:
 
 ```
-make ORG=wombat NOTRUST=1 push
+linuxkit pkg build -org=wombat -disable-content-trust push
 ```
 
 This will push both `wombat/<image>:<hash>-<arch>` and
@@ -100,7 +121,7 @@ Finally, if you are tired of the long hashes you can override the hash
 with:
 
 ```
-make ORG=wombat NOTRUST=1 HASH=foo push
+linuxkit pkg build -org=wombat -disable-content-trust -hash=foo push
 ```
 
 and this will create `wombat/<image>:foo-<arch>` and