#Adjust Dockerfile for Building Task-Compatible Custom Images

#Feature Overview

In Tekton, to enhance security, Tasks may be configured with runAsNonRoot: true, which requires containers to run as non-root users. Therefore, special attention must be given to the configuration of the Dockerfile when building custom images to ensure that the images can operate correctly in such Tasks.

This document describes how to adjust the Dockerfile to build custom images that are compatible with Tasks, focusing on user permission configurations.

#Use Cases

The following scenarios require referring to the guidance in this document:

• Building a custom image for use in Tasks
• Encountering permission-related errors when running existing images in Tasks
• Ensuring the image meets the security requirements of Tasks

#Prerequisites

Before using this feature, ensure:

• You have a Docker image building environment
  • You can use the platform's native build pipeline
  • If you need to use community/open-source tools, ensure you have internet access or have prepared offline packages
• You have a basic understanding of Dockerfile writing
  • You can refer to the Dockerfile Official Documentation
  • Understand Dockerfile Best Practices
• A Dockerfile file and related configuration

#Steps

#1. Confirm the Base Image

First, confirm the release version of the base image, as the command for creating a user may differ between versions:

# Check the release version of the base image
$ docker run -it --rm ${registry} cat /etc/os-release

# Possible outputs
NAME="Alpine Linux"
# or
NAME="Debian GNU/Linux"
# or
NAME="Ubuntu"
# or
NAME="CentOS Linux"

#2. Add a Non-Root User

Add a non-root user in the Dockerfile (it is recommended to use UID 65532):

# Based on the base image, choose the corresponding command

# Alpine
RUN adduser -u 65532 -h /home/nonroot -D nonroot

# Debian
RUN adduser --home /home/nonroot --uid 65532 nonroot --disabled-password --gecos ""

# Ubuntu
RUN apt-get update && apt-get install -y adduser \
    && adduser --home /home/nonroot --uid 65532 nonroot --disabled-password --gecos ""

# CentOS
RUN groupadd -g 65532 nonroot && useradd -u 65532 -U -d /home/nonroot -m nonroot

#3. Set Necessary Permissions for the User (Optional)

If the user needs to access certain directories or files, necessary permissions should be added for that user.

# Set the owner of the directory or file to nonroot
RUN chown -R nonroot:nonroot /path/to/directory

# Alternatively, set the permissions of the directory or file to allow everyone to read and write or to other minimal permissions
RUN chmod -R a+rwx /path/to/directory

#4. Set the Default User

Set the default user in the Dockerfile (using UID instead of the username):

Since Pods configured with runAsNonRoot will check if the user ID is a non-root user rather than checking the username.

# Set the default user to nonroot (using UID)
USER 65532

#5. Validate the Image

After building, validate whether the image can run correctly:

# Verify user configuration
$ docker run -it --rm ${registry} id

# Expected output
uid=65532(nonroot) gid=65532(nonroot) groups=65532(nonroot)

# Verify application permissions
$ docker run -it --rm ${registry} ls -la /home/nonroot

#Operation Results

With this configuration:

1. User Configuration

   • UID 65532 is consistently used, allowing files generated in multiple Tasks to have consistent access permissions
   • Ensure the user has appropriate working directory permissions
   • Avoid using the root user or UID 0

2. Application Configuration

   • Ensure applications can run normally as non-root users
   • Pre-configure necessary directory permissions in the Dockerfile
   • Use the VOLUME instruction to define directories that need to be persisted

3. Security Recommendations

   • Regularly update the base image to fix security vulnerabilities
   • Use multi-stage builds to reduce image size
   • Follow the principle of least privilege when configuring user permissions

#Troubleshooting

If permission issues occur when running the image in Tasks, you can:

1. Check the error messages in Pod events
2. Verify if the user configuration in the image is correct
3. Ensure that the required permissions for the application are configured

#Learn More

• Dockerfile Official Documentation
• Dockerfile Best Practices