heyvaldemar/aws-kubectl-docker

# aws-kubectl Docker 镜像 [](https://hub.docker.com/r/heyvaldemar/aws-kubectl) [](https://hub.docker.com/r/heyvaldemar/aws-kubectl/tags) [](https://github.com/heyvaldemar/aws-kubectl-docker/actions/workflows/publish.yml) [](https://opensource.org/licenses/MIT) 此镜像通过在 **Ubuntu 24.04** 上捆绑 **AWS CLI v2** (`aws`) 和 **kubectl**，简化了 Amazon Web Services (AWS) 和 Kubernetes 的工作。它还包含 `jq`、`curl`、`unzip` 和 `envsubst`（来自 `gettext-base`）。非常适合 CI/CD 步骤、自动化以及可复现的本地脚本编写。 🐳 Docker Hub: [heyvaldemar/aws-kubectl](https://hub.docker.com/r/heyvaldemar/aws-kubectl) ## v2.0 中的重大变更 从 **v2.0.0** 开始，此镜像默认以**非 root 用户 (UID 10001, GID 0)** 运行。这符合现代容器安全最佳实践，并且是兼容 OpenShift、受限的 Kubernetes PodSecurityPolicy 配置文件以及企业安全扫描器所必需的。 ### 对于大多数用户：无需更改 如果您将此镜像用于一次性 CI 命令（`aws s3 sync`、`kubectl apply`），v2.0 的工作方式与 v1.x 完全相同。 ### 对于挂载卷的用户 如果您挂载了主机目录或 Kubernetes PVC，您可能需要调整文件所有权或使用匹配的 UID 运行容器： **Docker:** ``` docker run --rm -v "$PWD:/home/app" --user "$(id -u):0" \ heyvaldemar/aws-kubectl:latest aws s3 ls ``` **Kubernetes:** ``` spec: securityContext: runAsUser: 10001 runAsGroup: 0 fsGroup: 0 ``` ### 保持在 v1.x 如果 v2.0 破坏了您的工作流并且您需要时间进行迁移，请固定到 v1 维护版本： ``` docker pull heyvaldemar/aws-kubectl:v1-maintenance ``` `v1-maintenance` 标签将在 **2026 年 7 月 20 日**之前接收安全更新，之后将被冻结。 ## 功能 - **Ubuntu 24.04** 基础镜像，确保稳定性。 - **AWS CLI v2** 用于完整的 AWS 管理。 - **kubectl**（固定特定版本或在构建时使用最新的稳定版本）。 - 预装了 `jq`、`curl`、`unzip`、`envsubst` 和 `ca-certificates`。 - **多阶段构建**：仅用于构建的中间产物（AWS CLI zip、解压的目录树、kubectl 归档文件）绝不会进入最终镜像。 - 在构建期间对 `kubectl` 进行**校验和验证**。 - 使用 `buildx` 构建/推送时支持**多架构** (amd64/arm64)。 - 每个发布的镜像上都带有 **OCI 标签** (`org.opencontainers.image.*`)。 - 解析后的 **kubectl 版本**写入镜像内的 `/etc/kube-version`。 ## 供应链 - 基础镜像通过 `sha256` 摘要进行固定 (`ubuntu:24.04@sha256:…`)。Dependabot 的 `docker` 生态系统每周更新一次摘要。 - 多阶段 `Dockerfile` 确保仅用于构建的中间产物（下载的 AWS CLI 归档文件、解压的目录树、kubectl tarball 和校验和文件）不会出现在发布的镜像中。 - 构建期间，`kubectl` 二进制文件会与 `dl.k8s.io` 上发布的上游 `sha256` 校验和进行验证。 - 每周定期的重建会获取 Ubuntu 基础镜像的安全更新 (`cron: "0 6 * * 1"`)。 - CI 在任何构建运行之前，会使用 `hadolint` 对 Dockerfile 进行代码检查，并使用 `shellcheck` 对 shell 脚本进行代码检查。 - 所有第三方 GitHub Actions 都固定到带有版本注释的 commit SHA。 - 构建参数 `VCS_REF` 和 `BUILD_DATE` 被标记到 `org.opencontainers.image.revision` 和 `org.opencontainers.image.created` 中，解析后的 kubectl 版本通过 `io.heyvaldemar.kubectl.version` 和 `/etc/kube-version` 公开。 - 每个发布的摘要都通过 Sigstore 无密钥 OIDC 使用此仓库的 GitHub Actions 身份进行 **cosign 签名**。 - **SBOM**（由 BuildKit 生成的 SPDX）和 **SLSA 构建来源** (`provenance: mode=max`) 附加到每个发布的镜像。 - **GitHub 原生构建来源**通过 `actions/attest-build-provenance` 进行证明，并与镜像一起推送到 registry。 - **Trivy** 在每次推送时扫描发布的镜像；可修复的 CRITICAL 和 HIGH 发现作为 SARIF 上传到仓库的 GitHub Security 标签页。 ### 验证签名 ``` cosign verify heyvaldemar/aws-kubectl:latest \ --certificate-identity-regexp "https://github.com/heyvaldemar/aws-kubectl-docker/.*" \ --certificate-oidc-issuer "https://token.actions.githubusercontent.com" ``` ### 标签管理 标签分为四类： - **语义化版本发布** (`:2.0.0`, `:2.0`, `:2`, `:v2.0.0`) — 不可变，永久保留。推荐用于生产环境的固定版本。 - **浮动通道** (`:latest`, `:edge`, `:v1-maintenance`) — 在每次主构建时更新；永久保留。 - **Kubernetes 版本固定** (`:kube-v1.35.4`) — 跟踪打包到镜像中的 kubectl 版本。永久保留。 - **短 SHA 构建** (`:sha-<7char>`) — 由 CI 为每个提交到 main 分支的代码生成。保留 90 天，然后由 `Docker Hub Tag Cleanup` 工作流自动删除。 Cosign 签名 (`:sha256-.sig`) 由 Sigstore 管理，不会被删除。 ## 使用场景 - **CI/CD**: 在流水线中运行 `aws`/`kubectl` 步骤。 - **本地开发**: 在将其整合到自动化流程之前测试命令。 - **脚本编写**: 一致且可移植的工具包装器。 ## 前置条件 - `~/.aws` – AWS 凭证/配置 (`credentials`, `config`)。挂载到容器内的 `/home/app/.aws`。 - `~/.kube` – kubeconfig(s)。挂载到容器内的 `/home/app/.kube`。 ## 运行容器 带有两种配置的交互式 shell（挂载在 `/home/app` —— 非 root 用户的 `HOME` 目录下 —— 并匹配您的宿主机 UID，以便容器能够读取挂载的文件）： ``` docker run -it \ --user "$(id -u):0" \ -v ~/.aws:/home/app/.aws \ -v ~/.kube:/home/app/.kube \ heyvaldemar/aws-kubectl bash ``` 如果您在 ARM/M 系列 Mac 上拉取了仅支持 **amd64** 的标签： ``` docker run --platform linux/amd64 -it \ --user "$(id -u):0" \ -v ~/.aws:/home/app/.aws \ -v ~/.kube:/home/app/.kube \ heyvaldemar/aws-kubectl bash ``` ### 直接执行命令（不启动 shell） ``` # 列出 S3 buckets docker run --rm \ --user "$(id -u):0" \ -v ~/.aws:/home/app/.aws \ heyvaldemar/aws-kubectl aws s3 ls # 获取 Kubernetes nodes docker run --rm \ --user "$(id -u):0" \ -v ~/.kube:/home/app/.kube \ heyvaldemar/aws-kubectl kubectl get nodes ``` ## 构建说明 `Dockerfile` 接受以下构建参数： | ARG | 默认值 | 用途 | |--------------|------------|--------------------------------------------------------------------------| | `KUBE_VERSION` | `latest` | 固定特定的 `kubectl` 版本 (例如 `v1.30.6`)。`latest` 会从 `dl.k8s.io` 获取当前的稳定版本。 | | `VCS_REF` | `unknown`| Commit SHA，标记到 `org.opencontainers.image.revision` 中。 | | `BUILD_DATE` | `unknown`| ISO-8601 构建时间戳，标记到 `org.opencontainers.image.created` 中。| | `TARGETARCH` | auto | 目标架构 (`amd64`/`arm64`)。由 `buildx` 自动提供。| ### 本地单架构构建 (dev) ``` # 从包含 Dockerfile 的文件夹 docker build -t aws-kubectl:local . ``` ### 固定特定的 kubectl 版本 ``` docker build --build-arg KUBE_VERSION=v1.30.6 \ -t aws-kubectl:local . ``` 如果省略了 `KUBE_VERSION`，构建将从 `dl.k8s.io` 获取**最新的稳定版本**。 ### 标记修订版本和构建日期（推荐用于发布构建） ``` docker build \ --build-arg KUBE_VERSION=v1.30.6 \ --build-arg VCS_REF="$(git rev-parse HEAD)" \ --build-arg BUILD_DATE="$(date -u +'%Y-%m-%dT%H:%M:%SZ')" \ -t aws-kubectl:local . ``` ### 多架构构建并推送 (amd64 + arm64) ``` docker buildx create --name x --use || docker buildx use x # Generic tag（tag 中无 OS 名称） docker buildx build \ --platform linux/amd64,linux/arm64 \ --build-arg VCS_REF="$(git rev-parse HEAD)" \ --build-arg BUILD_DATE="$(date -u +'%Y-%m-%dT%H:%M:%SZ')" \ -t heyvaldemar/aws-kubectl:latest \ --push . # 或在用户可以理解的 tag 中固定 kubectl KUBE_VERSION=v1.30.6 docker buildx build \ --platform linux/amd64,linux/arm64 \ --build-arg KUBE_VERSION=$KUBE_VERSION \ --build-arg VCS_REF="$(git rev-parse HEAD)" \ --build-arg BUILD_DATE="$(date -u +'%Y-%m-%dT%H:%M:%SZ')" \ -t heyvaldemar/aws-kubectl:kube-$KUBE_VERSION \ --push . ``` 验证： ``` docker buildx imagetools inspect heyvaldemar/aws-kubectl:latest ``` ## 本地构建与测试（使用仓库脚本） 此仓库包含 `scripts/smoke-test.sh`，用于验证镜像中的工具。 1. **本地构建** ``` docker build -t aws-kubectl:local . ``` 2. **运行冒烟测试** ``` chmod +x scripts/smoke-test.sh ./scripts/smoke-test.sh # defaults to aws-kubectl:local ./scripts/smoke-test.sh your/tag:dev # test any tag you pass ``` 该脚本会检查： - OS/架构 - 版本：AWS CLI, kubectl (客户端), jq, envsubst, curl, unzip - `/etc/kube-version` 是否与 `kubectl version --client` 匹配 - 二进制文件位置和 CA 证书包 - HTTPS 可达性（仅标头） - （可选）如果您挂载了 `~/.aws` / `~/.kube`，则会进行 AWS STS + `kubectl` 集群调用 ## 快速验证（手动单行命令） ``` IMG=aws-kubectl:local # OS/arch docker run --rm $IMG sh -lc 'uname -a; echo -n "Arch: "; uname -m' # 核心工具 & 版本 docker run --rm $IMG aws --version docker run --rm $IMG kubectl version --client --output=yaml docker run --rm $IMG jq --version docker run --rm $IMG envsubst --version docker run --rm $IMG sh -c 'curl --version | head -n1' docker run --rm $IMG sh -c 'unzip -v | head -n2' # 在构建时标记已确定的 kubectl release docker run --rm $IMG cat /etc/kube-version # 二进制文件位于预期位置 docker run --rm $IMG sh -c 'ls -l /usr/local/bin/kubectl; for b in aws jq envsubst curl unzip; do command -v "$b"; done' # CA bundle 存在 + HTTPS 完整性 docker run --rm $IMG sh -c 'ls -lh /etc/ssl/certs/ca-certificates.crt' docker run --rm $IMG sh -c 'curl -fsSI -o /dev/null -w "HTTPS OK (%{http_code})\n" https://kubernetes.io' ``` ### 可选的“真实”检查（带有挂载配置） ``` # AWS identity（需要有效的 creds） docker run --rm --user "$(id -u):0" \ -v ~/.aws:/home/app/.aws \ aws-kubectl:local aws sts get-caller-identity # 当前 k8s context & nodes（需要有效的 kubeconfig） docker run --rm --user "$(id -u):0" \ -v ~/.kube:/home/app/.kube \ aws-kubectl:local kubectl config current-context docker run --rm --user "$(id -u):0" \ -v ~/.kube:/home/app/.kube \ aws-kubectl:local kubectl get nodes -o wide ``` ## 标签/版本控制策略 为了避免在文档中出现特定于操作系统的标签并保持使用的可预测性： - `latest` – 滚动更新的多架构构建，使用当前默认配置。 - `kube-` – 固定的 `kubectl` 版本（例如，`kube-1.30.6`）。 - `` – 绑定到 Git commit 的不可变构建（CI 友好）。 - 可选的**次要版本**滚动标签： - `kube-` → 浮动到该次要版本的最新补丁（例如，`kube-1.30` → `1.30.6`) ## 安全说明 - 从 v2.0 开始，默认以**非 root** 身份 (UID 10001, GID 0) 运行。 - `kubectl` 二进制文件在构建期间经过了**校验和验证**。 - APT 使用最小化安装 (`--no-install-recommends`) 并清理了软件源列表。 - 在 CI 中固定 `KUBE_VERSION` 以确保可复现性。 ## 以 root 身份运行（覆盖） 如果特定的工作流需要容器内有 root 权限（例如在运行时安装额外的 `apt` 软件包，或恢复 v2.0 之前的行为），请覆盖用户： ``` docker run --rm --user 0:0 heyvaldemar/aws-kubectl bash ```

标签：AWS, AWS CLI v2, Docker, Docker Hub, DPI, envsubst, jq, K8s运维工具, kubectl, OpenShift, Pandas, PodSecurityPolicy, SBOM认证, SOC Prime, Ubuntu 24.04, Web截图, 云运维, 多架构镜像, 安全防御评估, 容器安全, 容器镜像, 开发工具, 数字取证, 签名镜像, 自动化脚本, 请求拦截, 非root用户