<commit_before>.. only:: not (epub or latex or html)

    WARNING: You are looking at unreleased Cilium documentation.
    Please use the official rendered version released here:
    https://docs.cilium.io

.. _container_images:

Building Container Images
=========================

Two make targets exists to build container images automatically based on the
locally checked out branch:

Developer images
~~~~~~~~~~~~~~~~

Run ``make dev-docker-image`` to build a cilium-agent Docker image that
contains your local changes.

.. code-block:: shell-session

    ARCH=amd64 DOCKER_DEV_ACCOUNT=quay.io/myaccount DOCKER_IMAGE_TAG=jane-developer-my-fix make dev-docker-image

Run ``make docker-operator-generic-image`` (respectively,
``docker-operator-aws-image`` or ``docker-operator-azure-image``) to build the
cilium-operator Docker image:

.. code-block:: shell-session

    ARCH=amd64 DOCKER_DEV_ACCOUNT=quay.io/myaccount DOCKER_IMAGE_TAG=jane-developer-my-fix make docker-operator-generic-image

The commands above assumes that your username for ``quay.io`` is ``myaccount``.

~~~~~~~~~~~~~~
Race detection
~~~~~~~~~~~~~~

See section on :ref:`compiling Cilium with race detection
<compile-cilium-with-race-detection>`.

Official release images
~~~~~~~~~~~~~~~~~~~~~~~

Anyone can build official release images using the make target below.

.. code-block:: shell-session

    DOCKER_IMAGE_TAG=v1.4.0 make docker-images-all

Experimental Docker BuildKit and Buildx support
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Docker BuildKit allows build artifact caching between builds and
generally results in faster builds for the developer. Support can be
enabled by:

.. code-block:: shell-session

    export DOCKER_BUILDKIT=1

Multi-arch image build support for arm64 (aka aarch64) and amd64 (aka
x86-64) can be enabled by defining:

.. code-block:: shell-session

    export DOCKER_BUILDX=1

Multi-arch images are built using a cross-compilation builder by
default, which uses Go cross compilation for Go targets, and QEMU
based emulation for other build steps. You can also define your own
Buildx builder if you have access to both arm64 and amd64 machines.
The "cross" builder will be defined and used if your current builder
is "default".

Buildx targets push images automatically, so you must also have
DOCKER_REGISTRY and DOCKER_DEV_ACCOUNT defined, e.g.:

.. code-block:: shell-session

    export DOCKER_REGISTRY=docker.io
    export DOCKER_DEV_ACCOUNT=your-account

Currently the cilium-runtime and cilium-builder images are released
for amd64 only (see the table below). This means that you have to
build your own cilium-runtime and cilium-builder images:

.. code-block:: shell-session

    make docker-image-runtime

After the build finishes update the runtime image references in other
Dockerfiles (``docker buildx imagetools inspect`` is useful for finding
image information). Then proceed to build the cilium-builder:

.. code-block:: shell-session

    make docker-image-builder

After the build finishes update the main Cilium Dockerfile with the
new builder reference, then proceed to build Hubble from
github.com/cilium/hubble. Hubble builds via buildx QEMU based
emulation, unless you have an ARM machine added to your buildx
builder:

.. code-block:: shell-session

    export IMAGE_REPOSITORY=${DOCKER_REGISTRY}/${DOCKER_DEV_ACCOUNT}/hubble
    CONTAINER_ENGINE="docker buildx" DOCKER_FLAGS="--push --platform=linux/arm64,linux/amd64" make image

Update the main Cilium Dockerfile with the new Hubble reference and
build the multi-arch versions of the Cilium images:

.. code-block:: shell-session

    make docker-images-all

Official Cilium repositories
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following table contains the main container image repositories managed by
Cilium team. It is planned to convert the build process for all images based
on GH actions.

+-------------------------------+---------------------------------------------+-----------------------------------------------+-------------------------+-------------------+
|     **Github Repository**     |                **Dockerfile**               |      **container image repository**           |   **Architectures**     | **Build process** |
|                               |                                             |                                               +-----------+-------------+                   |
|                               |                                             |                                               | **amd64** | **aarch64** |                   |<commit_msg>docs: Update docker build commands<commit_after>.. only:: not (epub or latex or html)

    WARNING: You are looking at unreleased Cilium documentation.
    Please use the official rendered version released here:
    https://docs.cilium.io

.. _container_images:

Building Container Images
=========================

Two make targets exists to build container images automatically based on the
locally checked out branch:

Developer images
~~~~~~~~~~~~~~~~

Run ``make dev-docker-image`` to build a cilium-agent Docker image that
contains your local changes.

.. code-block:: shell-session

    ARCH=amd64 DOCKER_DEV_ACCOUNT=quay.io/myaccount DOCKER_IMAGE_TAG=jane-developer-my-fix make dev-docker-image

Run ``make docker-operator-generic-image`` (respectively,
``docker-operator-aws-image`` or ``docker-operator-azure-image``) to build the
cilium-operator Docker image:

.. code-block:: shell-session

    ARCH=amd64 DOCKER_DEV_ACCOUNT=quay.io/myaccount DOCKER_IMAGE_TAG=jane-developer-my-fix make docker-operator-generic-image

The commands above assumes that your username for ``quay.io`` is ``myaccount``.

~~~~~~~~~~~~~~
Race detection
~~~~~~~~~~~~~~

See section on :ref:`compiling Cilium with race detection
<compile-cilium-with-race-detection>`.

Official release images
~~~~~~~~~~~~~~~~~~~~~~~

Anyone can build official release images using the make target below.

.. code-block:: shell-session

    DOCKER_IMAGE_TAG=v1.4.0 make docker-images-all

Experimental Docker BuildKit and Buildx support
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Docker BuildKit allows build artifact caching between builds and
generally results in faster builds for the developer. Support can be
enabled by:

.. code-block:: shell-session

    export DOCKER_BUILDKIT=1

Multi-arch image build support for arm64 (aka aarch64) and amd64 (aka
x86-64) can be enabled by defining:

.. code-block:: shell-session

    export DOCKER_BUILDX=1

Multi-arch images are built using a cross-compilation builder by
default, which uses Go cross compilation for Go targets, and QEMU
based emulation for other build steps. You can also define your own
Buildx builder if you have access to both arm64 and amd64 machines.
The "cross" builder will be defined and used if your current builder
is "default".

Buildx targets push images automatically, so you must also have
DOCKER_REGISTRY and DOCKER_DEV_ACCOUNT defined, e.g.:

.. code-block:: shell-session

    export DOCKER_REGISTRY=docker.io
    export DOCKER_DEV_ACCOUNT=your-account

Currently the cilium-runtime and cilium-builder images are released
for amd64 only (see the table below). This means that you have to
build your own cilium-runtime and cilium-builder images:

.. code-block:: shell-session

    make -C images runtime-image

After the build finishes update the runtime image references in other
Dockerfiles (``docker buildx imagetools inspect`` is useful for finding
image information). Then proceed to build the cilium-builder:

.. code-block:: shell-session

    make -C images builder-image

After the build finishes update the main Cilium Dockerfile with the
new builder reference, then proceed to build Hubble from
github.com/cilium/hubble. Hubble builds via buildx QEMU based
emulation, unless you have an ARM machine added to your buildx
builder:

.. code-block:: shell-session

    export IMAGE_REPOSITORY=${DOCKER_REGISTRY}/${DOCKER_DEV_ACCOUNT}/hubble
    CONTAINER_ENGINE="docker buildx" DOCKER_FLAGS="--push --platform=linux/arm64,linux/amd64" make image

Update the main Cilium Dockerfile with the new Hubble reference and
build the multi-arch versions of the Cilium images:

.. code-block:: shell-session

    make docker-images-all

Official Cilium repositories
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following table contains the main container image repositories managed by
Cilium team. It is planned to convert the build process for all images based
on GH actions.

+-------------------------------+---------------------------------------------+-----------------------------------------------+-------------------------+-------------------+
|     **Github Repository**     |                **Dockerfile**               |      **container image repository**           |   **Architectures**     | **Build process** |
|                               |                                             |                                               +-----------+-------------+                   |
|                               |                                             |                                               | **amd64** | **aarch64** |                   |
{'fraction_non_alphanumeric': 0.14416078218359588, 'fraction_numerical': 0.00717001629549158, 'mean_word_length': 2.7165926524020994, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 23, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2395644', 'n_tokens_mistral': 2469, 'n_tokens_neox': 2284, 'n_words': 886}