热门搜索:
ghcr.io/kiwigrid/k8s-sidecar:1.28.1
ghcr.io
ghcr.iolinux/amd641.28.1大小: 未知更新于 2026年5月22日
功能介绍
这是一个 Docker 容器，旨在在 Kubernetes 集群内运行，用于收集带有指定标签的 ConfigMap，并将其中包含的文件存储到本地文件夹中。它还可以在 ConfigMap 变更后向指定 URL 发送 HTTP 请求。主要目标是作为 sidecar 容器运行，为应用程序提供来自集群的信息。
设计初衷
这是我们将 ConfigMap 或 Secret 中的文件提供给服务并在运行时保持更新的简单方式。
使用方法
将此仓库创建的容器与您的应用程序一起运行在单个 Pod 中，并使用共享卷。指定应监控的标签以及文件的存储位置。通过添加额外的环境变量，容器可以向指定 URL 发送 HTTP 请求。
镜像地址
镜像可在以下地址获取：
- docker.io/kiwigrid/k8s-sidecar
- quay.io/kiwigrid/k8s-sidecar
- ghcr.io/kiwigrid/k8s-sidecar
所有镜像均为相同的多架构镜像，支持 amd64、arm64 和 arm/v7。
amd64``arm64``arm/v7## 停止支持 ppc64le 和 s390x 架构
ppc64le``s390x从 v2.x 版本开始，我们已停止支持 ppc64le 和 s390x 架构。如果您仍需要这些架构的支持，请联系我们。一种可能的解决方案是使用原生运行器而非 qemu 设置专用构建任务。
ppc64le``s390x## 功能特性
- 从 ConfigMap 和 Secret 中提取文件
- 基于标签过滤
- ConfigMap 或 Secret 变更时进行更新/删除
- 强制唯一文件名
- 针对 k8s v1.25-v1.35 的 CI 测试
- 支持 Secret 和 ConfigMap 类型的 binaryData
- 二进制数据内容在生成磁盘文件前会进行 base64 解码
- 值也可以是 base64 编码的 URL，用于下载二进制数据（例如可执行文件）。ConfigMap/Secret 中的键必须以 ".url" 结尾（参见）
- ConfigMap/Secret 中的键必须以 ".url" 结尾（参见）
ConfigMap``Secret``.url## 使用说明
简单部署示例可在 example.yaml 中找到。根据集群设置，您可能需要先为自己授予管理员权限：
`example.yaml__CODE_TOKEN_0__
可以使用环境变量 FOLDER_ANNOTATION 定义的 ConfigMap 注解覆盖文件复制的默认目录（如果未设置，默认值为 k8s-sidecar-target-directory）。Sidecar 会尝试创建 ConfigMap 中定义的目录（如果不存在）。ConfigMap 注解示例：
`FOLDER_ANNOTATION``k8s-sidecar-target-directory````yaml metadata: annotations: k8s-sidecar-target-directory: "/path/to/target/directory"
如果文件名以 .url 后缀结尾，内容将被视为 URL，目标文件内容将从该 URL 下载。
`.url`## 配置 CLI 标志
| 名称 | 描述 | 是否必需 | 默认值 | 类型 |
|----------------------|----------------------------------------------------------------------|----------|--------|--------|
| --req-username-file | 包含用户名的文件路径，用于对 REQ_URL 的请求和 *.url 触发的请求进行基本身份验证。这会覆盖 REQ_USERNAME | false | - | string |
| --req-password-file | 包含密码的文件路径，用于对 REQ_URL 的请求和 *.url 触发的请求进行基本身份验证。这会覆盖 REQ_PASSWORD | false | - | string |
`--req-username-file``REQ_URL``*.url``REQ_USERNAME``--req-password-file``REQ_URL``*.url``REQ_PASSWORD`## 配置环境变量
| 名称 | 描述 | 是否必需 | 默认值 | 类型 |
|----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|--------------------------------------|--------|
| LABEL | 用于过滤的标签 | true | - | string |
| LABEL_VALUE | 要过滤资源的标签值。不设置值则匹配任何标签值 | false | - | string |
| FOLDER | 文件存放目录 | true | - | string |
| FOLDER_ANNOTATION | Sidecar 在 ConfigMap 中查找的注解，用于覆盖文件的目标目录。注解值可以是绝对路径或相对路径。相对路径相对于 FOLDER | false | k8s-sidecar-target-directory | string |
| NAMESPACE | 逗号分隔的命名空间列表。如果指定，sidecar 将在这些命名空间中搜索 ConfigMap。也可以指定 ALL 以在所有命名空间中搜索 | false | sidecar 运行所在的命名空间 | string |
| RESOURCE | Sidecar 监控的资源类型。选项：configmap、secret、both | false | configmap | string |
| RESOURCE_NAME | 逗号分隔的资源名称列表，由 sidecar 监控。项目可以前缀命名空间和资源类型。例如 secret/resource-name 或 namespace/secret/resource-name。设置此参数会导致 method 设为 WATCH 时被视为 SLEEP ... | - | - | - |
| METHOD | ... | - | - | - |
| LIST | ... | - | - | - |
| SLEEP | ... | - | - | - |
| SLEEP_TIME | ... | - | 60 | - |
| REQ_URL | ... | - | - | - |
| REQ_METHOD | ... | - | GET | - |
| POST | ... | - | - | - |
| REQ_PAYLOAD | ... | - | - | - |
| REQ_METHOD=POST | ... | - | - | - |
| REQ_RETRY_TOTAL | ... | - | - | - |
| *.url | ... | - | - | - |
| REQ_URI | ... | - | - | - |
| REQ_RETRY_CONNECT | ... | - | 10 | - |
| REQ_RETRY_READ | ... | - | - | - |
| .url | ... | - | - | - |
| REQ_RETRY_BACKOFF_FACTOR | ... | - | 1.1 | - |
| REQ_TIMEOUT | ... | - | 10 | - |
| REQ_USERNAME | ... | - | - | - |
| REQ_PASSWORD | ... | - | - | - |
| REQ_BASIC_AUTH_ENCODING | ... | - | utf-8 | - |
| latin1 | ... | - | - | - |
| REQ_SKIP_INIT | ... | - | false | - |
| true | ... | - | - | - |
| SCRIPT | ... | - | - | - |
| sh | ... | - | - | - |
| #!/bin/sh | ... | - | - | - |
| #!/usr/bin/env python | ... | - | - | - |
| ERROR_THROTTLE_SLEEP | ... | - | - | - |
| SKIP_TLS_VERIFY | ... | - | - | - |
| true | ... | - | - | - |
| DISABLE_X509_STRICT_VERIFICATION | ... | - | true | - |
| REQ_SKIP_TLS_VERIFY | ... | - | true | - |
| UNIQUE_FILENAMES | ... | - | false | - |
| DEFAULT_FILE_MODE | ... | - | - | - |
| KUBECONFIG | ... | - | ~/.kube/config | - |
| ENABLE_5XX | ... | - | true | - |
| WATCH_SERVER_TIMEOUT | ... | - | 60 | - |
| WATCH_CLIENT_TIMEOUT | ... | - | 66 | - |
| IGNORE_ALREADY_PROCESSED | ... | - | false | - |
| LOG_LEVEL | ... | - | INFO | - |
| LOG_FORMAT | ... | - | JSON | - |
| LOG_TZ | ... | - | LOCAL | - |
| LOG_CONFIG | ... | - | LOG_LEVEL, LOG_FORMAT and LOG_TZ | - |
| HEALTH_PORT | ... | - | 8080 | - |
Sidecar 在端口 8080（或由 HEALTH_PORT 配置）上提供 /healthz 健康检查端点，可用于 Kubernetes 就绪探针和存活探针。该端点同时支持 IPv4 和 IPv6（双栈）。
`/healthz``8080``HEALTH_PORT`## 就绪探针
该端点仅在所有已配置资源（ConfigMap 和/或 Secret）的初始同步完成后返回 HTTP 200 OK。在此之前，将返回 HTTP 503 Service Unavailable。这确保主应用容器在其配置完全可用之前不会启动或接收流量。
`HTTP 200 OK``ConfigMap``Secret``HTTP 503 Service Unavailable`就绪探针配置示例：
```yaml
readinessProbe:
httpGet:
path: /healthz
port: 8080
initialDelaySeconds: 20
periodSeconds: 5
存活探针
该端点还用作存活探针，检查以下两个条件：
- Kubernetes API 连接：验证 sidecar 在过去 60 秒内是否成功连接到 Kubernetes API。
- 监控线程：确保所有内部监控线程（针对 ConfigMap 和 Secret）正常运行。
ConfigMap``Secret如果任何检查失败，端点将返回 HTTP 503 Service Unavailable，通知 Kubernetes 重启容器。
HTTP 503 Service Unavailable存活探针配置示例：
livenessProbe:
httpGet:
path: /healthz
port: 8080
initialDelaySeconds: 35
periodSeconds: 10
CI 和发布工作流
本仓库使用三个主要的 GitHub Actions 工作流：
1. 构建和测试（.github/workflows/build_and_test.yaml）
.github/workflows/build_and_test.yaml目的：在本地 kind 集群上对 sidecar 进行端到端测试。
kind- 触发条件：pull_request、workflow_dispatch
- pull_request
pull_request- workflow_dispatchworkflow_dispatch- 功能：构建 sidecar 的本地 Docker 镜像（不推送到任何 registry）。构建虚拟服务器镜像。将两个镜像加载到 kind 集群中。针对多个 Kubernetes 版本（矩阵）运行综合测试套件。
轩辕镜像配置手册
探索更多轩辕镜像的使用方法，找到最适合您系统的配置方式
Docker 配置
登录仓库拉取
通过 Docker 登录认证访问私有仓库
专属域名拉取
无需登录使用专属域名
K8s Containerd
Kubernetes 集群配置 Containerd
K3s
K3s 轻量级 Kubernetes 镜像加速
Dev Containers
VS Code Dev Containers 配置
Podman
Podman 容器引擎配置
Singularity/Apptainer
HPC 科学计算容器配置
其他仓库配置
ghcr、Quay、nvcr 等镜像仓库
Harbor 镜像源配置
Harbor Proxy Repository 对接专属域名
Portainer 镜像源配置
Portainer Registries 加速拉取
Nexus 镜像源配置
Nexus3 Docker Proxy 内网缓存
系统配置
需要其他帮助？请查看我们的 常见问题Docker 镜像访问常见问题解答 或 提交工单
镜像拉取常见问题
使用与功能问题
配置了专属域名后，docker search 为什么会报错？
docker search 限制
Docker Hub 上有的镜像，为什么在轩辕镜像网站搜不到？
站内搜不到镜像
机器不能直连外网时，怎么用 docker save / load 迁镜像？
离线 save/load
docker pull 拉插件报错（plugin v1+json）怎么办？
插件要用 plugin install
WSL 里 Docker 拉镜像特别慢，怎么排查和优化？
WSL 拉取慢
轩辕镜像安全吗？如何用 digest 校验镜像没被篡改？
安全与 digest
第一次用轩辕镜像拉 Docker 镜像，要怎么登录和配置？
新手拉取配置
轩辕镜像合规吗？轩辕镜像的合规是怎么做的？
镜像合规机制
轩辕镜像支持 docker push 上传本地镜像吗？
不支持 push
错误码与失败问题
docker pull 提示 manifest unknown 怎么办？
manifest unknown
docker pull 提示 no matching manifest 怎么办？
no matching manifest（架构）
镜像已拉取完成，却提示 invalid tar header 或 failed to register layer 怎么办？
invalid tar header（解压）
Docker pull 时 HTTPS / TLS 证书验证失败怎么办？
TLS 证书失败
Docker pull 时 DNS 解析超时或连不上仓库怎么办？
DNS 超时
docker 无法连接轩辕镜像域名怎么办？
域名连通性排查
Docker 拉取出现 410 Gone 怎么办？
410 Gone 排查
出现 402 或「流量用尽」提示怎么办？
402 与流量用尽
Docker 拉取提示 UNAUTHORIZED（401）怎么办？
401 认证失败
遇到 429 Too Many Requests（请求太频繁）怎么办？
429 限流
docker login 提示 Cannot autolaunch D-Bus，还算登录成功吗？
D-Bus 凭证提示
为什么会出现「单层超过 20GB」或 413，无法加速拉取？
413 与超大单层
账号 / 计费 / 权限
用户好评
来自真实用户的反馈，见证轩辕镜像的优质服务
oldzhang
运维工程师
Linux服务器
5
"Docker访问体验非常流畅，大镜像也能快速完成下载。"