#Adjust Containerfile for Building Task-Compatible Custom Images

#Feature Overview

在 Tekton 中，为了增强安全性，Tasks 可能会配置 runAsNonRoot: true，这要求容器以非 root 用户身份运行。因此，在构建自定义镜像时，需要特别注意 Containerfile 的配置，以确保镜像能够在此类 Tasks 中正常运行。

本文档介绍如何调整 Containerfile，以构建兼容 Tasks 的自定义镜像，重点关注用户权限配置。

#Use Cases

以下场景需要参考本文档的指导：

• 构建用于 Tasks 的自定义镜像
• 在 Tasks 中运行现有镜像时遇到权限相关错误
• 确保镜像满足 Tasks 的安全要求

#Prerequisites

使用此功能前，请确保：

• 具备 OCI 镜像构建环境
  • 可以使用平台的原生构建流水线
  • 若需使用 community/开源工具，确保具备网络访问或已准备好离线包
• 具备 Containerfile 编写的基础知识
  • 可参考 Dockerfile 官方文档
  • 理解 Dockerfile 最佳实践
• 拥有 Containerfile 文件及相关配置

#Steps

#1. Confirm the Base Image

首先，确认基础镜像的发行版本，因为不同版本创建用户的命令可能不同：

# 检查基础镜像的发行版本
$ podman run -it --rm ${registry} cat /etc/os-release

# 可能的输出
NAME="Alpine Linux"
# 或
NAME="Debian GNU/Linux"
# 或
NAME="Ubuntu"
# 或
NAME="CentOS Linux"

#2. Add a Non-Root User

在 Containerfile 中添加非 root 用户（建议使用 UID 65532）：

# 根据基础镜像选择对应命令

# 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)

如果用户需要访问某些目录或文件，应为该用户添加必要的权限。

# 将目录或文件的所有者设置为 nonroot
RUN chown -R nonroot:nonroot /path/to/directory

# 或者，将目录或文件权限设置为允许所有人读写，或其他最小权限
RUN chmod -R a+rwx /path/to/directory

#4. Set the Default User

在 Containerfile 中设置默认用户（使用 UID 而非用户名）：

由于配置了 runAsNonRoot 的 Pod 会检查用户 ID 是否为非 root 用户，而非用户名。

# 设置默认用户为 nonroot（使用 UID）
USER 65532

#5. Validate the Image

构建完成后，验证镜像是否能正常运行：

# 验证用户配置
$ podman run -it --rm ${registry} id

# 预期输出
uid=65532(nonroot) gid=65532(nonroot) groups=65532(nonroot)

# 验证应用权限
$ podman run -it --rm ${registry} ls -la /home/nonroot

#Operation Results

通过此配置：

1. 用户配置

   • 统一使用 UID 65532，确保多个 Tasks 生成的文件具有一致的访问权限
   • 确保用户拥有适当的工作目录权限
   • 避免使用 root 用户或 UID 0

2. 应用配置

   • 确保应用能以非 root 用户正常运行
   • 在 Containerfile 中预先配置必要的目录权限
   • 使用 VOLUME 指令定义需要持久化的目录

3. 安全建议

   • 定期更新基础镜像以修复安全漏洞
   • 使用多阶段构建以减小镜像体积
   • 配置用户权限时遵循最小权限原则

#Troubleshooting

若在 Tasks 中运行镜像时出现权限问题，可以：

1. 检查 Pod 事件中的错误信息
2. 验证镜像中的用户配置是否正确
3. 确认应用所需权限是否已配置

#Learn More

• Dockerfile 官方文档
• Dockerfile 最佳实践