Skip to content

Commit

Permalink
README.md: rephrase asz/ansible terms
Browse files Browse the repository at this point in the history
Drop the name Zeppelin for asz.

Rephrase some explanations to use the standard ansible terms, control
node and managed node.

Adjust the urls to be named anchors to simplify linking.
  • Loading branch information
michael131468 committed Mar 1, 2024
1 parent 6f6e867 commit 9ce86e7
Show file tree
Hide file tree
Showing 3 changed files with 53 additions and 49 deletions.
102 changes: 53 additions & 49 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,88 +1,98 @@
# asz

Automotive-SIG Zeppelin - Take your automotive-sig builds to the clouds
Take your automotive-sig builds to the clouds

## About

Zeppelin is a meta build system for the [Automotive-SIG sample-images][1]
project with the goal being to enable building customised AutoSD system images
using the cloud.
Asz (Automotive-Sig Zeppelin) is a meta build system for the [Automotive-SIG
sample-images][automotive_sig] project with the goal being to enable building
customised AutoSD system images using the cloud.

Zeppelin at this time only supports building either locally (on supported
distros) or on [Hetzner Cloud][2]. Thanks to their current low pricing for
Ampere vCPUs (at the time of writing), this means being able to assemble
aarch64 system images without emulation for only a few cents per build!
Asz at this time supports building either locally (on supported distros) or on
[Hetzner Cloud][hetzner_cloud] or on [AWS EC2][aws_ec2]. Thanks to Hetzner's
current low pricing for Ampere vCPUs (at the time of writing), this means being
able to assemble aarch64 system images without emulation for only a few cents
per build!

[automotive_sig]: https://sigs.centos.org/automotive/
[hetzner_cloud]: https://www.hetzner.com/cloud
[aws_ec2]: https://aws.amazon.com/ec2/

## Background

The [CentOS Automotive-SIG project][3] provides a Makefile-based build system to
assemble system-images (with OSBuild). This build system supports configuration
via both command line parameters and custom yaml snippet files that extend /
overwrite the default image configuration.
The [CentOS Automotive-SIG project][sample_images] provides a Makefile-based
build system to assemble system-images (with OSBuild). This build system
supports configuration via both command line parameters and custom yaml snippet
files that extend / overwrite the default image configuration.

The aim of Zeppelin is to add (yet another) abstraction layer to operate that
The aim of asz is to add (yet another) abstraction layer to operate that
Makefile-based build system with the intended benefits of simplifying the
management of the configurations and abstracting out the host builder set up
(allowing you to transparently build in the cloud or locally with no change in
the build-system entrypoint).

For now, Zeppelin aims to focus on building with the [Hetzner Cloud][2]. Support
for more cloud providers and other potential build hosts will be added in the
future.
For now, asz aims to focus on building with the [Hetzner Cloud][hetzner_cloud].
Support for more cloud providers and other potential build hosts will be added
in the future.

[sample_images]: https://sigs.centos.org/automotive/building/#using-makefile-to-build-the-image

## How It Works

Zeppelin is a simple set of Ansible playbooks and roles with a configuration
file to control the build process. The playbooks are run on an Ansible host
machine (typically the developer machine). The playbooks can set up a build
host machine (eg. instantiate a machine in Hetzner Cloud), run the build
instructions remotely on the build host machine, and gather the output files
back to the Ansible Host local filesystem.
asz is a simple set of Ansible playbooks and roles with a configuration file to
control the build process. The playbooks are run on an Ansible control node
(typically the developer machine). The playbooks can spawn and set up a managed
node (eg. instantiate a machine in Hetzner Cloud), run the build instructions
remotely on the managed node, and gather the output files back to the control
node local filesystem to preserve before terminating the managed node.

![zeppelin-diagram](/docs/images/zeppelin-diagram.png)

This is a workflow which on the surface appears like a developer is running the
system images assembly locally when actually it will transparently be processed
in the cloud.

While the main example case is using the cloud as a source of build hosts,
the build host could also be the local Ansible host itself or another available
networked machine like a Raspberry Pi. Any host that Ansible can provision,
set up, and use to execute build instructions is viable with Zeppelin.
While the main example case is using the cloud as a source of build hosts, the
build host could also be the local control node itself or another available
networked machine like a Raspberry Pi. Any managed node that Ansible can
provision, set up, and use to execute build instructions is viable with asz.

The Ansible host machine also need not always be the developer machine. Another
use case of Zeppelin is running system-image assembly in a CI/CD workflow. There
the Ansible host machine would be the pipeline runner that executes the CI/CD
workflow (eg. GitHub runner). This could be useful to avoid needing Arm64
machines in the pipeline execution (which for example is not available
as a public GitHub runners) and aligning CI workflows with developer workflows.
The control node also need not always be the developer machine. Another use case
of asz is running system-image assembly in a CI/CD workflow. There the control
node would be the pipeline runner that executes the CI/CD workflow (eg. GitHub
runner). This could be useful to avoid needing Arm64 machines in the pipeline
execution (which for example is not available as a public GitHub runners) and
aligning CI workflows with developer workflows.

<a href="https://www.flaticon.com/free-icons/productivity" title="productivity icons">Productivity icons created by vectorsmarket15 - Flaticon</a>

<a href="https://www.flaticon.com/free-icons/server" title="server icons">Server icons created by vectorsmarket15 - Flaticon</a>

## Requirements

Since Zeppelin is based on Ansible, you must have it installed on the computer
that starts the build process (aka your personal computer). Typically you can
Since asz is based on Ansible, you must have it installed on the control node
that manages the build process (aka your personal computer). Typically you can
install Ansible with pip.

```
python3 -m pip install --user ansible
```

You can find out more [here][4] on how to install it.
You can find out more [here][ansible_install] on how to install it.

In addition to having installed ansible, you need the [community.general
Ansible collection][5] installed also.
Ansible collection][ansible_collections] installed also.

```
ansible-galaxy collection install community.general
```

[ansible_install]: https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html#installing-and-upgrading-ansible
[ansible_collectons]: https://galaxy.ansible.com/community/general

## Configuration

The build host and system-image target build configuration is defined in
The managed node and system-image target build configuration is defined in
`config.yaml`. This yaml file is loaded by the different roles to dynamically
configure them at runtime.

Expand All @@ -96,15 +106,15 @@ configure the system image build target:
- target_arch
- target_filetype

These variables align with the [Automotive-SIG Makefile targets][3] so you can
refer to their documentation for details.
These variables align with the [Automotive-SIG Makefile targets][sample_images]
so you can refer to their documentation for details.

In the future there will be a simple `configure.sh` to help generate this
configuration yaml.

## Usage

Zeppelin supports a variety of use cases and configuration/instructons differ
asz supports a variety of use cases and configuration/instructons differ
for each. Details for each use case can be found in the linked documents.

- [Running builds locally](docs/building-locally.md)
Expand All @@ -114,15 +124,15 @@ for each. Details for each use case can be found in the linked documents.

Some common scenarios are also documented:

- [How can I run Zeppelin locally with a modified sample-images repository?][faq1]
- [How can I run Zeppelin locally with a modified custom-images repository?][faq2]
- [How can I run asz locally with a modified sample-images repository?][faq1]
- [How can I run asz locally with a modified custom-images repository?][faq2]

[faq1]: /docs/faq/modified-sample-images.md
[faq2]: /docs/faq/modified-custom-images.md

## Output Directory

Zeppelin will create a directory named `out` in your current working directory
asz will create a directory named `out` in your current working directory
where `ansible-playbook` was called.

This `out` directory will be populated during the build process with the log
Expand All @@ -140,9 +150,3 @@ scripts may be added to the resulting directory.
## License

This project is licensed under the MIT license (see LICENSE file).

[1]: https://sigs.centos.org/automotive/
[2]: https://www.hetzner.com/cloud
[3]: https://sigs.centos.org/automotive/building/#using-makefile-to-build-the-image
[4]: https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html#installing-and-upgrading-ansible
[5]: https://galaxy.ansible.com/community/general
Binary file modified docs/images/zeppelin-diagram.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/zeppelin-diagram.xcf
Binary file not shown.

0 comments on commit 9ce86e7

Please sign in to comment.