Skip to content

Commit

Permalink
docs: update docs with v1.0.0 changes (#47)
Browse files Browse the repository at this point in the history 
* docs: update docs with v1.0.0 changes

Signed-off-by: mbshields <[email protected]>

* docs: update What's New for v1.0.0, add SBOM article

Signed-off-by: mbshields <[email protected]>

* docs: resolve more PR comments

Signed-off-by: mbshields <[email protected]>

* docs: resolve comments, change zotregistry.io to .dev

Signed-off-by: mbshields <[email protected]>

---------

Signed-off-by: mbshields <[email protected]>
  • Loading branch information
@mbshields
mbshields authored Apr 8, 2024
1 parent b3e2a8c commit affffe8
Show file tree
Hide file tree
Showing 11 changed files with 351 additions and 89 deletions.
48 changes: 35 additions & 13 deletions docs/reference/stacker_cli.md
View file
Original file line number Diff line number Diff line change
@@ -1,18 +1,21 @@
# Stacker Command-Line Interface Reference

This document lists the command line interface (CLI) commands for stacker version 1.0.0.

<table>
<tr><td><a href="#stacker">stacker</a></td><td>Stacker builds OCI images</td></tr>
<tr><td><a href="#stacker-build">stacker build</a></td><td>Build a new OCI image from a stacker yaml file</td></tr>
<tr><td><a href="#stacker-recursive-build">stacker recursive-build</a></td><td>Find stacker yaml files under a directory and builds all OCI layers they define</td></tr>
<tr><td><a href="#stacker-publish">stacker publish</a></td><td>Publish OCI images previously built from one or more stacker yaml files</td></tr>
<tr><td><a href="#stacker-chroot-exec">stacker chroot</a></td><td>Run a command in a chroot (same as <code>stacker exec</code>)</td></tr>
<tr><td><a href="#stacker-clean">stacker clean</a></td><td>Clean up after a stacker build</td></tr>
<tr><td><a href="#stacker-inspect">stacker inspect</a></td><td>Print the json representation of an OCI image</td></tr>
<tr><td><a href="#stacker-grab">stacker grab</a></td><td>Grab a file from the layer's filesystem</td></tr>
<tr><td><a href="#stacker-unpriv-setup">stacker unpriv-setup</a></td><td>Do the necessary unprivileged setup for stacker build to work without root</td></tr>
<tr><td><a href="#stacker-build">stacker build</a></td><td>Builds a new OCI image from a stacker yaml file</td></tr>
<tr><td><a href="#stacker-recursive-build">stacker recursive-build</a></td><td>Finds stacker yaml files under a directory and builds all OCI images they define</td></tr>
<tr><td><a href="#stacker-convert">stacker convert</a></td><td>Converts a Dockerfile into a stacker yaml file</td></tr>
<tr><td><a href="#stacker-publish">stacker publish</a></td><td>Publishes OCI images previously built from one or more stacker yaml files</td></tr>
<tr><td><a href="#stacker-chroot-exec">stacker chroot</a></td><td>Runs a command in a chroot (same as <code>stacker exec</code>)</td></tr>
<tr><td><a href="#stacker-clean">stacker clean</a></td><td>Cleans up after a stacker build</td></tr>
<tr><td><a href="#stacker-inspect">stacker inspect</a></td><td>Prints the json representation of an OCI image</td></tr>
<tr><td><a href="#stacker-grab">stacker grab</a></td><td>Grabs a file from the image's filesystem</td></tr>
<tr><td><a href="#stacker-unpriv-setup">stacker unpriv-setup</a></td><td>Does the necessary unprivileged setup for stacker build to work without root</td></tr>
<tr><td><a href="#stacker-gc">stacker gc</a></td><td>Garbage collection of unused OCI imports/outputs snapshots</td></tr>
<tr><td><a href="#stacker-check">stacker check</a></td><td>Check that all runtime required items (like kernel features) are present</td></tr>
<tr><td><a href="#stacker-help">stacker help</a></td><td>Show a list of commands or help for one command</td></tr>
<tr><td><a href="#stacker-check">stacker check</a></td><td>Checks that all runtime required items (like kernel features) are present</td></tr>
<tr><td><a href="#stacker-help">stacker help</a></td><td>Shows a list of commands or help for one command</td></tr>
</table>

<a name="stacker"></a>
Expand All @@ -26,11 +29,12 @@
stacker [global options] command [command options] [arguments...]

VERSION:
stacker v0.40.1-e54a685 liblxc a330126b45c7c3b6fcf0f9ba6c1eda7bdb4e508a
stacker <version> liblxc <digest>

COMMANDS:
build builds a new OCI image from a stacker yaml file
recursive-build finds stacker yaml files under a directory and builds all OCI layers they define
convert converts a Dockerfile into a stacker yaml file (experimental, best-effort)
publish publishes OCI images previously built from one or more stacker yaml files
chroot, exec run a command in a chroot
clean cleans up after a `stacker build`
Expand All @@ -42,10 +46,11 @@
help, h Shows a list of commands or help for one command

GLOBAL OPTIONS:
--work-dir value set the working directory for stacker's cache, OCI output and rootfs output
--stacker-dir value set the directory for stacker's cache (default: ".stacker")
--oci-dir value set the directory for OCI output (default: "oci")
--roots-dir value set the directory for the rootfs output (default: "roots")
--config value stacker config file with defaults (default: "/users/mishield/.config/stacker/conf.yaml")
--config value stacker config file with defaults (default: "/home/<username>/.config/stacker/conf.yaml")
--debug enable stacker debug mode
-q, --quiet silence all logs
--log-file value log to a file instead of stderr
Expand Down Expand Up @@ -102,6 +107,21 @@
--stacker-file-pattern value, -p value regex pattern to use when searching for stackerfile paths (default: "\\/stacker.yaml$")
--search-dir value, -d value directory under which to search for stackerfiles to build (default: ".")

<a name="stacker-convert"></a>

## stacker convert

NAME:
stacker convert - converts a Dockerfile into a stacker yaml file (experimental, best-effort)

USAGE:
stacker convert [command options] [arguments...]

OPTIONS:
--docker-file value, -i value the input Dockerfile (default: "Dockerfile")
--output-file value, -o value the output stacker file (default: "stacker.yaml")
--substitute-file value, -s value the output file containing detected substitutions (default: "stacker-subs.yaml")

<a name="stacker-publish"></a>

## stacker publish
Expand All @@ -115,6 +135,7 @@
OPTIONS:
--stacker-file value, -f value the input stackerfile (default: "stacker.yaml")
--stacker-file-pattern value, -p value regex pattern to use when searching for stackerfile paths (default: "\\/stacker.yaml$")
--substitute-file value file containing variable substitution in stackerfiles, 'FOO: bar' yaml format
--search-dir value, -d value directory under which to search for stackerfiles to publish
--url value url where to publish the OCI images
--username value username for the registry where the OCI images are published
Expand All @@ -125,6 +146,7 @@
--show-only show the images to be published without actually publishing them
--force force publishing the images present in the OCI layout even if they should be rebuilt
--layer-type value set the output layer type (supported values: tar, squashfs); can be supplied multiple times (default: "tar")
--image value image to be published; can be specified multiple times

<a name="stacker-chroot-exec"></a>

Expand Down Expand Up @@ -157,7 +179,7 @@
stacker clean [command options] [arguments...]

OPTIONS:
--all no-op; this used to do soemthing, and is left in for compatibility
--all no-op; this used to do something, and is left in for compatibility

<a name="stacker-inspect"></a>

Expand Down
84 changes: 39 additions & 45 deletions docs/reference/stacker_file.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -63,50 +63,42 @@ layer on a previously specified layer in the stacker file.

`scratch`: which is an empty rootfs and can be used to host statically built binaries.

### `import`
### `imports`

The `import` directive describes what files should be made available in
`/stacker` during the `run` phase. There are three forms of importing supported
today:
The `imports` directive describes what files should be made available in `/stacker/imports` during the `run` phase. There are three forms of importing supported today:

/path/to/file

Will import a file or directory from the local filesystem. If the file or
directory changes between stacker builds, it will be hashed and the new file
will be imported on subsequent builds.
Will import a file or directory from the local filesystem. If the file or directory changes between stacker builds, it will be hashed and the new file will be imported on subsequent builds.

http://example.com/foo.tar.gz

Will import foo.tar.gz and make it available in `/stacker`. Note that stacker
will NOT update this file unless the cache is cleared, to avoid excess network
usage. That means that updates after the first time stacker downloads the file
will not be reflected.
Will import foo.tar.gz and make it available in `/stacker`. Note that stacker will NOT update this file unless the cache is cleared, to avoid excess network usage. That means that updates after the first time stacker downloads the file will not be reflected.

stacker://$name/path/to/file

Will grab /path/to/file from the previously built layer `$name`.
Will grab /path/to/file from the previously built image `$name`.

#### `import hash`

The `import` directive also supports specifying the hash(sha256sum) of import source,
for all the three forms presented above, for example:
Each entry in the `import` directive also supports specifying the hash (sha256sum) of import source, for all the three forms presented above. For example:
```
import:
imports:
- path: config.json
hash: f55af805b012017bc....
- path: http://example.com/foo.tar.gz
hash: b458dfd63e7883a64....
- path: stacker://$name/path/to/file
hash: f805b012017bc769a....
```
Before copying the file it will check if the requested hash matches the actual one.
Before copying the file, stacker will check that the file's hash matches the given value. For file imports, the source file is hashed at build time. For HTTP imports, the value returned by the server in the `X-Checksum-Sha256` HTTP header is checked first. If that value matches, the file is downloaded and then hashed and compared again.

`stacker build` supports the flag `--require-flag` which checks that all http(s) remote
imports have an hash in all stacker YAMLs.
`stacker build` supports the flag `--require-hash`, which will cause a build error if any HTTP(S) remote imports do not have a hash specified, in all transitively included stacker YAMLs.

If `--require-hash` is not passed, this import mode can be combined with unchecked imports, and only files that have the hash specified will be checked.

This new import mode can be combined with the old one, for example:
```
import:
imports:
- path: "config.json
hash: "BEEFcafeaaaaAAAA...."
- /path/to/file
Expand All @@ -116,13 +108,17 @@ import:

The `import` directive also supports specifying the destination path (specified
by `dest`) in the resulting container image, where the source file (specified
by `path`) will be copyied to, for example:
by `path`) will be copyed to. For example:
```
import:
imports:
- path: config.json
dest: /
```

### `import` (Deprecated)

The deprecated `import` directive operates like `imports` except that the entries in the `import` array will be placed into `/stacker` instead of `/stacker/imports`.

### `overlay_dirs`
This directive works only with OverlayFS backend storage.

Expand All @@ -146,7 +142,7 @@ to be available under container's /usr/local/ and all the files/dirs from the ho
These correspond exactly to the similarly named bits in the [OCI image
config
spec](https://github.com/opencontainers/image-spec/blob/master/config.md#properties),
and are available for users to pass things through to the runtime environment
and are available for users to pass variables through to the runtime environment
of the image.

### `generate_labels`
Expand All @@ -163,19 +159,17 @@ be the label content.
By default, environment variables do not pass through (pollute) the
build environment.

`build_env`: this is a dictionary with environment variable definitions.
their values will be present in the build's environment.
`build_env`: A dictionary of environment variable definitions. The values will be present in the build's environment.

`build_env_passthrough`: This is a list of regular expressions that work as a
`build_env_passthrough`: A list of regular expressions that work as a
filter on which environment variables should be passed through from the current
env into the container. To let all variables through simply set
env into the container. To let all variables through, simply set
`build_env_passthrough`: `[".*"]`

If `build_env_passthrough` is not set, then the default value is to allow
through proxy variables `HTTP_PROXY, HTTPS_PROXY, FTP_PROXY, http_proxy,
https_proxy, ftp_proxy`.
If `build_env_passthrough` is not set, the default behavior is to allow
through proxy variables `HTTP_PROXY, HTTPS_PROXY, FTP_PROXY, http_proxy, https_proxy, ftp_proxy`.

Values in the `build_env` override values passed through via
Values in the `build_env` override values passed through via `build_env_passthrough`.

### `full_command`

Expand All @@ -199,18 +193,18 @@ not include all of its build dependencies.
- /foo/bar -> /bar/baz
- /zomg

The first one binds /foo/bar to /bar/baz, and the second host /zomg to
The first binds /foo/bar to /bar/baz, and the second binds host /zomg to
container /zomg.

Right now there is no awareness of change for any of these bind mounts, so
--no-cache should be used to re-build if the content of the bind mount has
At this time there is no awareness of change for any of these bind mounts, so
`--no-cache` should be used to re-build if the content of the bind mount has
changed.

### `config`

`config` key is a special type of entry in the root in the `stacker.yaml` file.
It cannot contain a layer definition, it is used to provide configuration
applicable for building all the layers defined in this file. For example,
The `config` key is a special type of entry in the root of the `stacker.yaml` file.
It cannot contain an image definition; it is used to provide configuration
applicable for building all the images defined in this file. For example,

config:
prerequisites:
Expand All @@ -220,17 +214,17 @@ applicable for building all the layers defined in this file. For example,
#### `prerequisites`

If the `prerequisites` list is present under the `config` key, stacker will
make sure to build all the layers in the stacker.yaml files found at the paths
contained in the list. This way stacker supports building multiple
make sure to build all the images in the stacker.yaml files found at the paths
contained in the list. In this way, stacker supports building multiple
stacker.yaml files in the correct order.

In this particular case the parent folder of the current folder, let's call it
`parent`, has 3 subfolders `folder1`, `folder2` and `folder3`, each containing a
In this particular case, the parent folder of the current folder, let's call it
`parent`, has 3 subfolders (`folder1`, `folder2`, and `folder3`), each containing a
`stacker.yaml` file. The example `config` above is in `parent/folder1/stacker.yaml`.

When `stacker build -f parent/folder1/stacker.yaml` is invoked, stacker would search
for the other two stacker.yaml files and build them first, before building
the stacker.yaml specified in the command line.
When `stacker build -f parent/folder1/stacker.yaml` is invoked, stacker searches
for the other two stacker.yaml files and builds them first, before building
the stacker.yaml file specified in the command line.

#### `annotations`

Expand All @@ -242,7 +236,7 @@ itself and not as part of the index.json.
a.b.c.key: abc_val
p.q.r.key: pqr_val

While `config` section supports a similar `labels`, it is more pertitent to the
While the `config` section supports a similar `labels`, it is more pertinent to the
image runtime. On the other hand, `annotations` is intended to be
image-specific metadata aligned with the
[annotations in the image spec](https://github.com/opencontainers/image-spec/blob/main/annotations.md).
Expand Down
2 changes: 1 addition & 1 deletion docs/user_guide/annotation_support.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ itself and not as part of the index.json.
a.b.c.key: abc_val
p.q.r.key: pqr_val

While `config` section supports a similar `labels`, it is more pertitent to the
While the `config` section supports a similar `labels`, it is more pertinent to the
image runtime. On the other hand, `annotations` is intended to be
image-specific metadata aligned with the
[annotations in the image spec](https://github.com/opencontainers/image-spec/blob/main/annotations.md).
32 changes: 32 additions & 0 deletions docs/user_guide/convert_dockerfile.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
# Convert a Dockerfile to stacker yaml

When moving a project from a docker build environment to a stacker build environment, you can use the [`stacker convert`](../reference/stacker_cli.md#stacker-convert) command to create a stacker yaml file from the existing Dockerfile.

!!! note

The conversion is a best-effort process and may not be successful in all cases.

During the conversion, variables from the Dockerfile may be exported to a substitution file, which can be declared in the `stacker build` command when building the project.

When invoking the `stacker convert` command, you have the option to specify the input (Dockerfile) filename, an output (stacker) filename, and a name for a substitution file, if such a file is generated by the conversion. Alternatively, you can use the default names provided:


| Command option | Abbreviation | Default name |
| --- | --- | --- |
| --docker-file | -i | "Dockerfile" |
| --output-file | -o | "stacker.yaml" |
| --substitute-file | -s | "stacker-subs.yaml" |


To execute a conversion, use the following syntax:

stacker convert [-i <name>] [-o <name>] [-s <name>]









Loading

0 comments on commit affffe8

Please sign in to comment.