Chapter 8. Building container images
Chapter 8. Building container images Building container images involves creating a blueprint for a containerized application. Blueprints rely on base images from other public repositories that define how the application should be installed and configured. Note Because blueprints rely on images from other public repositories, they might be subject to rate limiting. Consequently, your build could fail. Quay.io supports the ability to build Docker and Podman container images. This functionality is valuable for developers and organizations who rely on container and container orchestration. On Quay.io, this feature works the same across both free, and paid, tier plans. Note Quay.io limits the number of simultaneous builds that a single user can submit at one time. 8.1. Build contexts When building an image with Docker or Podman, a directory is specified to become the build context . This is true for both manual Builds and Build triggers, because the Build that is created by Quay.io is not different than running docker build or podman build on your local machine. Quay.io Build contexts are always specified in the subdirectory from the Build setup, and fallback to the root of the Build source if a directory is not specified. When a build is triggered, Quay.io Build workers clone the Git repository to the worker machine, and then enter the Build context before conducting a Build. For Builds based on .tar archives, Build workers extract the archive and enter the Build context. For example: Extracted Build archive example ├── .git ├── Dockerfile ├── file └── subdir └── Dockerfile Imagine that the Extracted Build archive is the directory structure got a Github repository called example. If no subdirectory is specified in the Build trigger setup, or when manually starting the Build, the Build operates in the example directory. If a subdirectory is specified in the Build trigger setup, for example, subdir , only the Dockerfile within it is visible to the Build. This means that you cannot use the ADD command in the Dockerfile to add file , because it is outside of the Build context. Unlike Docker Hub, the Dockerfile is part of the Build context on Quay.io. As a result, it must not appear in the .dockerignore file. 8.2. Tag naming for Build triggers Custom tags are available for use in Quay.io. One option is to include any string of characters assigned as a tag for each built image. Alternatively, you can use the following tag templates on the Configure Tagging section of the build trigger to tag images with information from each commit: USD{commit} : Full SHA of the issued commit USD{parsed_ref.branch} : Branch information (if available) USD{parsed_ref.tag} : Tag information (if available) USD{parsed_ref.remote} : The remote name USD{commit_info.date} : Date when the commit was issued USD{commit_info.author.username} : Username of the author of the commit USD{commit_info.short_sha} : First 7 characters of the commit SHA USD{committer.properties.username} : Username of the committer This list is not complete, but does contain the most useful options for tagging purposes. You can find the complete tag template schema on this page . For more information, see Set up custom tag templates in build triggers for Red Hat Quay and Quay.io 8.3. Skipping a source control-triggered build To specify that a commit should be ignored by the Quay.io build system, add the text [skip build] or [build skip] anywhere in your commit message. 8.4. Viewing and managing builds Repository Builds can be viewed and managed on the Quay.io UI. Procedure Navigate to Quay.io and select a repository. In the navigation pane, select Builds . 8.5. Creating a new Build By default, Quay.io users can create new Builds out-of-the-box. Prerequisites You have navigated to the Builds page of your repository. Procedure On the Builds page, click Start New Build . Alternatively, you can click the + icon to reveal a drop-down menu. When prompted, click Select File to upload a Dockerfile or an archive (for example, a .tar.gz or .zip file) that contains a Dockerfile at the root directory. Click Start Build . Note Currently, users cannot specify the Docker build context when manually starting a build. You are redirected to the Build, which can be viewed in real-time. Wait for the Dockerfile Build to be completed and pushed. Optional. you can click Download Logs to download the logs, or Copy Logs to copy the logs. Click the back button to return to the Repository Builds page, where you can view the Build History. 8.6. Build triggers Build triggers invoke builds whenever the triggered condition is met, for example, a source control push, creating a webhook call , and so on. 8.6.1. Creating a Build trigger Use the following procedure to create a Build trigger. Prerequisites You have navigated to the Builds page of your repository. Procedure On the Builds page, click Create Build Trigger . Select the desired platform, for example, Github, BitBucket, Gitlab, or use a custom Git repository. For this example, we are using Github. If prompted, confirm access to your account. When prompted, select an organization. You can filter namespaces by including text in the Filter namespaces... box. Alternatively, you can scroll your namespaces by clicking the directional arrows. If the organization that you are trying to select is not listed, click Connections wih Quay Container Registry to request, or grant yourself, access. Click Continue after you have selected an organization. When prompted, select a repository. Then, click Continue . Configure the trigger by selecting one of the following options: Trigger for all branches and tags (default1) . By selecting this option, a container image for each commit across all branches and tags is created. Trigger only on branches and tags matching a regular expression . By selecting this option, only container images for a subset of branches and/or tags are built. Click Continue . When prompted, configure the tagging options by selecting one of, or both of, the following options: Tag manifest with the branch or tag name . When selecting this option, the built manifest the name of the branch or tag for the git commit are tagged. Add latest tag if on default branch . When selecting this option, the built manifest with latest if the build occurred on the default branch for the repository are tagged. Optional. Add a custom tagging template. There are multiple tag templates that you can enter here, including using short SHA IDs, timestamps, author names, committer, and branch names from the commit as tags. For more information, see "Understanding tag naming for Build triggers". Click Continue . When prompted, select the location of the Dockerfile to be built when the trigger is invoked. If the Dockerfile is located at the root of the git repository and named Dockerfile, enter /Dockerfile as the Dockerfile path. Click Continue . When prompted, select the context for the Docker build. If the Dockerfile is located at the root of the Git repository, enter / as the build context directory. Check for any verification warnings. If necessary, fix the issues before clicking Continue . When prompted with Ready to go! , click Continue . You are redirected to a confirmation page. Save the SSH Public Key, then click Return to <organization_name>/<repository_name> . You are redirected to the Builds page of your repository. On the Builds page, you now have a Build trigger. For example: 8.6.2. Manually triggering a Build Builds can be triggered manually by using the following procedure. Procedure On the Builds page, click the cog wheel , or Options icon, and select Run Trigger Now . When prompted, click the dropdown menu to specify a branch or tag, then click Start Build . After the build starts, you can see the Build ID on the Repository Builds page. 8.7. Setting up a custom Git trigger A custom Git trigger is a generic way for any Git server to act as a Build trigger. It relies solely on SSH keys and webhook endpoints. Everything else is left for the user to implement. 8.7.1. Creating a trigger Creating a custom Git trigger is similar to the creation of any other trigger, with the exception of the following: Quay.io cannot automatically detect the proper Robot Account to use with the trigger. This must be done manually during the creation process. There are extra steps after the creation of the trigger that must be done. These steps are detailed in the following sections. 8.7.2. Custom trigger creation setup When creating a custom Git trigger, two additional steps are required: You must provide read access to the SSH public key that is generated when creating the trigger. You must setup a webhook that POSTs to the Quay.io endpoint to trigger the build. The key and the URL are available by selecting View Credentials from the Settings , or gear icon. View and modify tags from your repository 8.7.2.1. SSH public key access Depending on the Git server configuration, there are multiple ways to install the SSH public key that Quay.io generates for a custom Git trigger. For example, Git documentation describes a small server setup in which adding the key to USDHOME/.ssh/authorize_keys would provide access for Builders to clone the repository. For any git repository management software that is not officially supported, there is usually a location to input the key often labeled as Deploy Keys . 8.7.2.2. Webhook To automatically trigger a build, one must POST a .json payload to the webhook URL using the following format. This can be accomplished in various ways depending on the server setup, but for most cases can be done with a post-receive Git Hook . Note This request requires a Content-Type header containing application/json in order to be valid. Example webhook { "commit": "1c002dd", // required "ref": "refs/heads/master", // required "default_branch": "master", // required "commit_info": { // optional "url": "gitsoftware.com/repository/commits/1234567", // required "message": "initial commit", // required "date": "timestamp", // required "author": { // optional "username": "user", // required "avatar_url": "gravatar.com/user.png", // required "url": "gitsoftware.com/users/user" // required }, "committer": { // optional "username": "user", // required "avatar_url": "gravatar.com/user.png", // required "url": "gitsoftware.com/users/user" // required } } }
example ├── .git ├── Dockerfile ├── file └── subdir └── Dockerfile { "commit": "1c002dd", // required "ref": "refs/heads/master", // required "default_branch": "master", // required "commit_info": { // optional "url": "gitsoftware.com/repository/commits/1234567", // required "message": "initial commit", // required "date": "timestamp", // required "author": { // optional "username": "user", // required "avatar_url": "gravatar.com/user.png", // required "url": "gitsoftware.com/users/user" // required }, "committer": { // optional "username": "user", // required "avatar_url": "gravatar.com/user.png", // required "url": "gitsoftware.com/users/user" // required } } }