Hacking on the infrastructure

After making changes to Ansible or any other component of the gateway image, it is recommended to test the changes by either re-generating the gateway image, or running the ansible playbook against a live instance of the gateway.

You may then submit these changes, according to the Contributing guide, assuming no AI/LLM was used to create them.

Vivian instance

For an already-running vivian instance (started using make vivian), you can re-run the provisioning playbook to apply your changes:

$ make vivian-provision

If you want to iterate faster, you may limit the ansible job to some roles by using the TAGS= parameter:

$ make TAGS=dashboard,minio,executor vivian-provision

You can get a full list of available tags by running:

$ ansible-playbook --list-tags ansible/gateway.yml

If you need to pass additionnal arguments to Ansible use the ANSIBLE_EXTRA_ARGS= parameter.

Dedicated gateways

For a dedicated gateway, use the live-provision target:

$ make live-provision TARGET=my-farm [SSH_PORT=12345]

Where TARGET is the hostname of the gateway you want to provision, and SSH_PORT being ci-tron container’s sshd port (defaults to 22).

The TAGS= and ANSIBLE_EXTRA_ARGS= parameters are also available.

Warning

As a prerequisite, check the development machine has network connectivity to the gateway. Then make sure your public key is present in the container’s /config/ssh/authorized_keys. Finally update the host key by running ssh-keyscan -H my-farm >> ~/.ssh/known_hosts as the default Ansible options mandate host key verification with the live-provision target.

Building the container

The container image is built using rootless podman, and is provisioned using Ansible recipes (see the ansible/ subproject).

The following is a (likely incomplete) list of dependencies for a system running Debian/Ubuntu:

$ apt install buildah \
    git \
    jq \
    make \
    netcat-openbsd \
    podman \
    python \
    qemu-utils \
    qemu-system \
    skopeo \
    socat \
    wget

Note: In order to reduce round-trips to an external registry, a local registry is automatically started when running certain make targets.

The container image can be built with:

$ make gateway

Build options

  • V=1 Turn on more verbose logging messages in the build process

  • ANSIBLE_EXTRA_ARGS="-vvv ..." Pass any custom flags to ansible-playbook. Helpful for re-running only tagged roles in the ansible build, for example. You can also use this to override variables used by the ansible playbook, for example: ANSIBLE_EXTRA_ARGS="-e foo=bar"

  • IMAGE_NAME=localhost:8088/my/image The container name to tag the image with. WARNING: The image will automatically be pushed to the registry that got tagged! Defaults to localhost:8088/gfx-ci/ci-tron/gateway:latest.

Once completed, a container image will be generated, for example,

Successfully tagged localhost:8088/gfx-ci/ci-tron/gateway:latest
60cc3db9bedd2a11d8d61a4433a2a8e8daf35a59d6229b80c1fdcf9ece73b7ab

Notice that it defaults to a localhost registry. This is to save on bandwidth, since the CI-tron container is quite big.