Skip to content

Docs: Add documentation for using BuildKit to build Docker images without privileged mode

Problem to solve

Our Docker-related documentation (https://docs.gitlab.com/ci/docker/) should be updated to address customer questions about secure alternatives to Kaniko.

Customers have asked how to build Docker images without privileged mode, following the principle of least privilege. With Kaniko no longer maintained by Google, we need to document modern alternatives that provide the same security benefits.

BuildKit, the build engine used by Docker, offers multiple approaches for secure container image building. Users can leverage BuildKit through Docker Buildx (familiar Docker commands), native BuildKit commands (advanced control), or BuildKit rootless (maximum security without Docker daemon dependency).

BuildKit rootless is particularly valuable as a direct Kaniko replacement because it eliminates both privileged containers and Docker daemon dependencies while providing enhanced features like multi-platform builds and advanced caching.

Related documentation:

Further details

This work addresses specific customer questions:

  • What is the best way to build Docker images without privileged mode now that Kaniko is deprecated?
  • What modern alternatives provide equivalent or better security than Kaniko?
  • How can users migrate from Kaniko while maintaining the same security posture?

This documentation benefits DevOps engineers and security-focused users who need to build Docker images securely without compromising on security principles.

Proposal

  1. Create comprehensive BuildKit documentation page titled "Build Docker images with BuildKit" that covers:

    • Three distinct approaches (Docker Buildx, BuildKit with Docker daemon, BuildKit rootless)
    • Clear comparison table helping users choose the right approach
    • BuildKit rootless positioned as the direct Kaniko replacement
    • Multi-platform builds, advanced caching, and secure secret handling
    • Registry authentication for various scenarios
    • Migration guide from Kaniko with command mapping
    • Advanced configurations (proxy, custom certificates)
    • Focused troubleshooting for BuildKit-specific issues

  2. Update existing documentation:

    • Update main Docker integration page to reference BuildKit alternatives
    • Cross-reference from other Docker-related pages

  3. Improve navigation structure:

    • Position BuildKit documentation prominently as the modern, secure solution
    • Organize Docker building methods by security characteristics
    • Ensure easy discovery for users seeking Kaniko alternatives

This approach provides a comprehensive solution for users seeking secure, modern alternatives to Kaniko while maintaining compatibility with existing Docker workflows.

Other links/references

Edited by Lysanne Pinto