Skip to content

Latest commit

 

History

History
244 lines (175 loc) · 7.51 KB

devctr-image.md

File metadata and controls

244 lines (175 loc) · 7.51 KB
Raw

Publishing a New Container Image

What's the Container Image?

Firecracker uses a Docker container to standardize the build process. This also fixes the build tools and dependencies to specific versions. Every once in a while, something needs to be updated. To do this, a new container image needs to be built locally, then published to the Docker registry. The Firecracker CI suite must also be updated to use the new image.

Prerequisites

  1. A Docker account. You must create this by yourself on Docker hub.
  2. Access to the fcuvm Docker organization.
  3. The docker package installed locally. You should already have this if you've ever built Firecracker from source.
  4. Access to both an x86_64 and aarch64 machines to build the container images.

Steps

x86_64

  1. Login to the Docker organization in a shell. Use your username and password (not fcuvm).

    docker login

  2. Navigate to the Firecracker directory. Verify that you have the latest container image locally.

    docker images
REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
fcuvm/dev           v14                 9bbc159ad600        2 months ago        2.31GB

  3. Make your necessary changes, if any, to the Dockerfile(s). There's one for each supported architecture in the Firecracker source tree.

  4. Commit the changes, if any.

  5. Build a new container image with the updated Dockerfile.

     docker build -t fcuvm/dev -f tools/devctr/Dockerfile.x86_64 .

  6. Verify that the new image exists.

    docker images
REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
fcuvm/dev           latest              402b87586d11        5 minutes ago       2.31GB
fcuvm/dev           v14                 9bbc159ad600        2 months ago        2.31GB

  7. Tag the new image with the next available version and the architecture you're on.

    docker tag 402b87586d11 fcuvm/dev:v15_x86_64

docker images
REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
fcuvm/dev           latest              402b87586d11        5 minutes ago       2.31GB
fcuvm/dev           v15_x86_64          402b87586d11        5 minutes ago       2.31GB
fcuvm/dev           v14                 9bbc159ad600        2 months ago        2.31GB

  8. Push the image.

    docker push fcuvm/dev:v15_x86_64

aarch64

Login to the aarch64 build machine.

Steps 1-4 are identical across architectures, change x86_64 to aarch64.

Then:

  1. Build a new container image with the updated Dockerfile.

    docker build -t fcuvm/dev -f tools/devctr/Dockerfile.aarch64  .

  2. Verify that the new image exists.

    docker images
REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
fcuvm/dev           latest              402b87586d11        5 minutes ago       2.31GB
fcuvm/dev           v14                 c8581789ead3        2 months ago        2.31GB

  3. Tag the new image with the next available version and the architecture you're on.

    docker tag 402b87586d11 fcuvm/dev:v15_aarch64
    docker images
REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
fcuvm/dev           latest              402b87586d11        5 minutes ago       2.31GB
fcuvm/dev           v15_aarch64         402b87586d11        5 minutes ago       2.31GB
fcuvm/dev           v14                 c8581789ead3        2 months ago        2.31GB

  4. Push the image.

    docker push fcuvm/dev:v15_aarch64

  5. Create a manifest to point the latest container version to each specialized image, per architecture.

    docker manifest create fcuvm/dev:v15 fcuvm/dev:v15_x86_64 fcuvm/dev:v15_aarch64
docker manifest push fcuvm/dev:v15

  6. Update the image tag in the devtool script. Commit and push the change.

    sed -i 's%DEVCTR_IMAGE="fcuvm/dev:v14"%DEVCTR_IMAGE="fcuvm/dev:v15"%' tools/devtool

Troubleshooting

Check out the rust-vmm-container readme for additional troubleshooting steps and guidelines.

I can't push the manifest

docker manifest is only supported when experimental cli features are enabled

See this article for explanations and fix.

How can I test the image after pushing it to the Docker registry?

Either fetch and run it locally on another machine than the one you used to build it, or clean up any artifacts from the build machine and fetch.

docker system prune -a

docker images
REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE

tools/devtool shell
[Firecracker devtool] About to pull docker image fcuvm/dev:v15
[Firecracker devtool] Continue?

I don't have access to the Docker registry

docker push fcuvm/dev:v15
The push refers to repository [docker.io/fcuvm/dev]
e2b5ee0c4e6b: Preparing
0fbb5fd5f156: Preparing
...
a1aa3da2a80a: Waiting
denied: requested access to the resource is denied

Only a Firecracker maintainer can update the container image. If you are one, ask a member of the team to add you to the fcuvm organization and retry.

I pushed the wrong tag

Tags can be deleted from the Docker's repository WebUI.

Also, pushing the same tag twice will overwrite the initial content.

I did everything right and nothing works anymore

If you see unrelated Python errors, it's likely because the dev container pulls Python 3 at build time. Python 3 means different minor versions on different platforms, and is not backwards compatible. So it's entirely possible that docker build has pulled in unwanted Python dependencies.

To include only your changes, an alternative to the method described above is to make the changes inside the container, instead of in the Dockerfile.

Let's say you want to update cargo-audit (random example).

  1. Enter the container as root.

    tools/devtool shell -p

  2. Make the changes locally. Do not exit the container.

    cargo install cargo-audit --force

  3. Find your running container.

    docker ps
CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES
e9f0487fdcb9        fcuvm/dev:v14       "bash"              53 seconds ago      Up 52 seconds                           zen_beaver

  4. Commit the modified container to a new image. Use the container ID.

    docker commit e9f0487fdcb9 fcuvm/dev:v15_x86_64
    docker image ls
REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
fcuvm/dev           v15_x86_64          514581e654a6        18 seconds ago      2.31GB
fcuvm/dev           v14                 c8581789ead3        2 months ago        2.31GB

  5. Repeat for aarch64.

  6. Create and push the manifest.