Skip to content
P

Publish Container Registry Image CI/CD Catalog project

Welcome to the Publish Container Registry Image Wiki!

Overview

This component simplifies building and publishing Docker images with Kaniko in a GitLab CI/CD pipeline. It removes the need for privileged Docker access. You can use this component across multiple repositories, and it's customizable through inputs.

The process is broken into two stages:

  1. PrepKanikoParams: This stage sets up Kaniko parameters like Docker build arguments and image labels.
  2. BuildAndPublishDockerImage: Kaniko builds the Docker image using the parameters and pushes it to the GitLab Container Registry.

This pipeline is flexible and supports versioned image releases, helping with smooth deployments.

Pipeline Setup

To use this component in your GitLab pipeline, add it to your .gitlab-ci.yml file. You'll need to reference the template and pass in any necessary settings, like runner tags, build arguments, labels, and image versions.

Key Points

  • Inputs control settings like pipeline stage, Docker build arguments, and runner tags.
  • It's modular and reusable, so you can easily include it in multiple projects.

Configuration Inputs

You can adjust the build process using several inputs. Here's what they do:

  • stage: Specifies the pipeline stage (e.g., build, test, deploy) where the component will run. Defaults to "build."
  • runner-tags: Defines which GitLab runners will run the jobs.
  • build-args: Docker build arguments passed to the Dockerfile during the build. Use them to set environment variables or key-value pairs.
  • labels: Metadata attached to the Docker image, making it easier to manage. For example, you could label an image as "env=production" or "team=devops."
  • version: Specifies the image version, following semantic versioning (e.g., 1.0.0).
  • image-name: The name of the Docker image to be built and published. It will be used as the identifier in the registry.
  • dockerfile-path: Path to the Dockerfile used in the build. Useful if your Dockerfile is in a non-standard location or has a custom name. This should also allow you to use multiple dockerfile's in the same project.

These inputs allow you to tailor the pipeline to different projects, making it both flexible and reusable.

Pipeline Stages

The pipeline has two key stages:

  1. PrepKanikoParams:

    • In this stage, the component takes the inputs (like build arguments and labels) and prepares the parameters that Kaniko will use. These are saved in an environment file for the next stage.
    • This stage creates Kaniko-compatible labels and build arguments, formatted into command-line options, allowing you to customize the build process.

  2. BuildAndPublishDockerImage:

    • Kaniko builds the Docker image with the parameters from the first stage and pushes it to the GitLab Container Registry. It tags the image with both a specified version and latest to keep the most recent version accessible.
    • Kaniko works without privileged Docker access. This stage also handles authentication using the CI_REGISTRY, CI_REGISTRY_USER and CI_REGISTRY_PASSWORD pre-defined GitLab CI/CD variables.

These stages work together by separating the setup of parameters from the actual image building, which makes the pipeline simpler and more adaptable. One reason for this is that the Kaniko image doesn’t include a bash shell to handle the logic needed for creating the build arguments. In the future, I might build a custom Kaniko image to handle this more efficiently.

Example Usage

To use this component, include it in your .gitlab-ci.yml file and provide the required inputs for your project.

Using these inputs, you can set up the component for various projects without repeating complex CI/CD logic, making it reusable across different repositories.

Kaniko Parameter Generation

The PrepKanikoParams stage generates the parameters Kaniko needs during the build. This includes:

  • Generating Build Arguments: The build-args input is converted into --build-arg options for Kaniko.
  • Generating Labels: The labels input is turned into --label options for Kaniko.

These parameters are stored in the KANIKO_PARAMS environment variable, which is passed to the next stage.

Publish Container Registry Image

In the PublishContainerRegistryImage stage, Kaniko uses the parameters from the previous stage to build the Docker image. The image is pushed to the GitLab Container Registry with two tags:

  • A version-specific tag (e.g., 1.0.0) from the version input.
  • The latest tag, which points to the most recent image.

This ensures that both a versioned and latest version of the image are available in the registry.

Troubleshooting

Common Issues

  • Invalid Build or Label Arguments: If Kaniko fails due to invalid arguments, check the KANIKO_PARAMS generated in the PrepKanikoParams stage by reviewing the pipeline logs.

By following these steps and providing the right inputs, you can simplify your Docker image build and publish process, ensuring efficient CI/CD workflows across your projects.