Skip to content

Commit

Permalink
Merge pull request #88 from cevich/update_build-push_docs
Browse files Browse the repository at this point in the history 
[CI:DOCS] Update readme's
  • Loading branch information
@cevich
cevich authored Sep 23, 2021
2 parents 8edb596 + cd13b74 commit f4f1069
Show file tree
Hide file tree
Showing 2 changed files with 96 additions and 54 deletions.
115 changes: 78 additions & 37 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,51 +21,69 @@ preferably as root. The script ***must*** be passed the version number of [the
release to install](https://github.com/containers/automation/releases). Alternatively
it may be passed `latest` to install the HEAD of the main branch.

For example, to install the `v1.0.0` release, run:
```sh
# url='https://github.com/containers/automation/releases/latest/download/install_automation.sh'
# curl -sL "$url" | bash -s 1.1.3
For example, to install the `v1.1.3` release, run:
```bash
~# url='https://github.com/containers/automation/releases/latest/download/install_automation.sh'
~# curl -sL "$url" | bash -s 1.1.3
```

To install `latest`, run:
```sh
# url='https://github.com/containers/automation/releases/latest/download/install_automation.sh'
# curl -sL "$url" | bash -s latest
```bash
~# url='https://github.com/containers/automation/releases/latest/download/install_automation.sh'
~# curl -sL "$url" | bash -s latest
```

Optionally, the installer may also be passed the names of one or more components to
install system-wide. For example:

To install the latest `build-push`, run:
```sh
# url='https://github.com/containers/automation/releases/latest/download/install_automation.sh'
# curl -sL "$url" | bash -s latest build-push
```

## Alt. Installation
### Alt. Installation

If you're leery of piping to bash and/or a local clone of the repository is already
available locally, the installer can be invoked with the *magic version* '0.0.0'.
Note that this will limit the install to the local clone (as-is), the installer script
Note this will limit the install to the local clone (as-is). The installer script
will still reach out to github.com to retrieve version information. For example:

```sh
# cd /path/to/clone
# ./bin/install_automation.sh 0.0.0
```bash
~# cd /path/to/clone
/path/to/clone# ./bin/install_automation.sh 0.0.0
```

### Component installation

The installer may also be passed the names of one or more components to
install system-wide. Available components are simply any subdirectory in the repo
which contain a `.install.sh` file. For example, to install the latest `build-push` system-wide run:

```bash
~# url='https://github.com/containers/automation/releases/latest/download/install_automation.sh'
~# curl -sL "$url" | bash -s latest build-push
```

## Usage

The basic install consists of copying the contents of the `common` (subdirectory) and
the installer script into a central location on the system. Because this location
can vary, a global shell variable `$AUTOMATION_LIB_PATH` is widely used. Therefore,
it is highly recommended that all users and calling scripts explicitly load and export
env. var. definitions set in the file `/etc/automation_environment`. For example:

```sh
# set -a
# source /etc/automation_environment
# set +a
can vary by platform, a global shell variable `$AUTOMATION_LIB_PATH` is established
by a central configuration at install-time. It is highly recommended that all
callers explicitly load and export the contents of the file
`/etc/automation_environment` before making use of the common library or any
components. For example:

```bash
#!/bin/bash

set -a
if [[ -r "/etc/automation_environment" ]]; then
source /etc/automation_environment
fi
set +a

if [[ -n "$AUTOMATION_LIB_PATH" ]]; then
source $AUTOMATION_LIB_PATH/common_lib.sh
else
(
echo "WARNING: It doesn't appear containers/automation common was installed."
) > /dev/stderr
fi

...do stuff...
```


Expand All @@ -81,18 +99,41 @@ This directory contains scripts intended for execution under multiple environmen
pertaining to operations on this whole repository. For example, executing all
unit tests, installing components, etc.

### `build-push`

Handy automation too to help with parallel building and pushing container images,
including support for multi-arch (via QEMU emulation). See the
[README.md file in the subdirectory](build-push/README.md) for more information.

### `cirrus-ci_artifacts`

Handy python script that may be used to download artifacts from any build,
based on knowing its ID. Downloads will be stored properly nested, by task
name and artifact so there are no name clashes.

### `cirrus-ci_env`

Python script used to minimally parse `.cirrus.yml` tasks as written/formatted
in other containers projects. This is not intended to be used directly, but
called by other scripts to help extract env. var. values from matrix tasks.

### `cirrus-ci_retrospective`

See the [README.md file in the subdirectory](cirrus-ci_retrospective/README.md) for more information.

### `cirrus-task-map`

Handy script that parses a `.cirrus.yml` and outputs an flow-diagram to illustrate
task dependencies. Useful for visualizing complex configurations, like that of
`containers/podman`.

### `common`

This directory contains general-purpose scripts, libraries, and their unit-tests.
They're intended to be used individually or as a whole from within automation of
other repositories.

### `cirrus-ci_retrospective`

See the [README.md file in the subdirectory](cirrus-ci_retrospective/README.md) for more information

### `build-push`
### `github`

Handy automation too to help with parallel building and pushing container images,
including support for multi-arch (via QEMU emulation). See the
[README.md file in the subdirectory](build-push/README.md) for more information.
Contains some helper scripts/libraries for using `cirrus-ci_retrospective` from
within github-actions workflow. Not intended to be used otherwise.
35 changes: 18 additions & 17 deletions build-push/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,25 +23,26 @@ it may be useful on its own, this is not its primary purpose.

## QEMU-user-static Emulation

On platforms/distro's that support it, this is a handy way to enable
non-native binary execution. This can therefore be used to support
building container images for other architectures. Though other
techniques may be possible, there are [handy/dandy scripts and
container images available to help configure
this.](https://github.com/multiarch/qemu-user-static#multiarchqemu-user-static-images)

Using this in a reliable way under automation suggests pointing it
at the host's qemu-user-staic binaries instead of those bundled in
the container image (which may not even match the host platform).
Fortunately passing those in via volume-mount is pretty trivial.
Something like this (as **root** in Fedora):
On platforms/distro's that support it (Like F34+) this is a handy
way to enable non-native binary execution. It can therefore be
used to build container images for other non-native architectures.
Though setup may vary by distro/version, in F34 all that's needed
is to install the `qemu-user-static` package. It will take care
of automatically registering the emulation executables with the
kernel.

Otherwise, you may find these [handy/dandy scripts and
container images useful](https://github.com/multiarch/qemu-user-static#multiarchqemu-user-static-images) for environments without native support (like
CentOS and RHEL). However, be aware I cannot atest to the safety
or quality of those binaries/images, so use them at your own risk.
Something like this (as **root**):

```bash
$ sudo dnf install -y qemu-user-static
$ qemu_setup_fqin="docker.io/multiarch/qemu-user-static:latest"
$ vol_awk='{print "-v "$1":"$1""}'
$ bin_vols=$(find /usr/bin -name 'qemu-*-static' | awk -e "$vol_awk" | tr '\n' ' ')
$ sudo podman run --rm --privileged $bin_vols $qemu_setup_fqin --reset -p yes
~# install qemu user static binaries somehow
~# qemu_setup_fqin="docker.io/multiarch/qemu-user-static:latest"
~# vol_awk='{print "-v "$1":"$1""}'
~# bin_vols=$(find /usr/bin -name 'qemu-*-static' | awk -e "$vol_awk" | tr '\n' ' ')
~# podman run --rm --privileged $bin_vols $qemu_setup_fqin --reset -p yes
```

Note: You may need to alter `$vol_awk` or the `podman` command line
Expand Down

0 comments on commit f4f1069

Please sign in to comment.