配置 kubelet 镜像凭据提供程序
Kubernetes v1.26 [稳定]
从 Kubernetes v1.20 开始,kubelet 可以使用 exec 插件动态检索容器镜像仓库的凭据。kubelet 和 exec 插件通过 stdio(stdin、stdout 和 stderr)使用 Kubernetes 版本化的 API 进行通信。这些插件允许 kubelet 动态请求容器仓库的凭据,而不是将静态凭据存储在磁盘上。例如,该插件可以与本地元数据服务器通信,以检索 kubelet 拉取的镜像的短期凭据。
如果您符合以下任何情况,您可能需要使用此功能
- 需要向云提供商服务发出 API 调用以检索仓库的认证信息。
- 凭据的有效期很短,需要频繁请求新的凭据。
- 在磁盘或 imagePullSecrets 中存储仓库凭据不可接受。
本指南演示如何配置 kubelet 的镜像凭据提供程序插件机制。
开始之前
- 您需要一个 Kubernetes 集群,其节点支持 kubelet 凭据提供程序插件。此支持在 Kubernetes 1.30 中可用;Kubernetes v1.24 和 v1.25 包含此功能作为 beta 功能,默认情况下启用。
- 一个有效的凭据提供程序 exec 插件实现。您可以构建自己的插件或使用云提供商提供的插件。
kubectl version
。在节点上安装插件
凭据提供程序插件是一个可执行二进制文件,将由 kubelet 运行。确保插件二进制文件存在于集群中的每个节点上,并存储在已知目录中。稍后配置 kubelet 标志时将需要该目录。
配置 Kubelet
为了使用此功能,kubelet 预期设置两个标志
--image-credential-provider-config
- 凭据提供程序插件配置文件的路径。--image-credential-provider-bin-dir
- 凭据提供程序插件二进制文件所在的目录的路径。
配置 kubelet 凭据提供程序
传递给 --image-credential-provider-config
的配置文件由 kubelet 读取,以确定应为哪些容器镜像调用哪些 exec 插件。以下是一个示例配置文件,如果您使用的是 基于 ECR 的插件,您最终可能会使用它
apiVersion: kubelet.config.k8s.io/v1
kind: CredentialProviderConfig
# providers is a list of credential provider helper plugins that will be enabled by the kubelet.
# Multiple providers may match against a single image, in which case credentials
# from all providers will be returned to the kubelet. If multiple providers are called
# for a single image, the results are combined. If providers return overlapping
# auth keys, the value from the provider earlier in this list is used.
providers:
# name is the required name of the credential provider. It must match the name of the
# provider executable as seen by the kubelet. The executable must be in the kubelet's
# bin directory (set by the --image-credential-provider-bin-dir flag).
- name: ecr-credential-provider
# matchImages is a required list of strings used to match against images in order to
# determine if this provider should be invoked. If one of the strings matches the
# requested image from the kubelet, the plugin will be invoked and given a chance
# to provide credentials. Images are expected to contain the registry domain
# and URL path.
#
# Each entry in matchImages is a pattern which can optionally contain a port and a path.
# Globs can be used in the domain, but not in the port or the path. Globs are supported
# as subdomains like '*.k8s.io' or 'k8s.*.io', and top-level-domains such as 'k8s.*'.
# Matching partial subdomains like 'app*.k8s.io' is also supported. Each glob can only match
# a single subdomain segment, so `*.io` does **not** match `*.k8s.io`.
#
# A match exists between an image and a matchImage when all of the below are true:
# - Both contain the same number of domain parts and each part matches.
# - The URL path of an matchImages must be a prefix of the target image URL path.
# - If the matchImages contains a port, then the port must match in the image as well.
#
# Example values of matchImages:
# - 123456789.dkr.ecr.us-east-1.amazonaws.com
# - *.azurecr.io
# - gcr.io
# - *.*.registry.io
# - registry.io:8080/path
matchImages:
- "*.dkr.ecr.*.amazonaws.com"
- "*.dkr.ecr.*.amazonaws.com.cn"
- "*.dkr.ecr-fips.*.amazonaws.com"
- "*.dkr.ecr.us-iso-east-1.c2s.ic.gov"
- "*.dkr.ecr.us-isob-east-1.sc2s.sgov.gov"
# defaultCacheDuration is the default duration the plugin will cache credentials in-memory
# if a cache duration is not provided in the plugin response. This field is required.
defaultCacheDuration: "12h"
# Required input version of the exec CredentialProviderRequest. The returned CredentialProviderResponse
# MUST use the same encoding version as the input. Current supported values are:
# - credentialprovider.kubelet.k8s.io/v1
apiVersion: credentialprovider.kubelet.k8s.io/v1
# Arguments to pass to the command when executing it.
# +optional
# args:
# - --example-argument
# Env defines additional environment variables to expose to the process. These
# are unioned with the host's environment, as well as variables client-go uses
# to pass argument to the plugin.
# +optional
env:
- name: AWS_PROFILE
value: example_profile
providers
字段是 kubelet 使用的已启用插件的列表。每个条目都有一些必填字段
name
: 插件的名称,必须与传递给--image-credential-provider-bin-dir
的目录中存在的可执行二进制文件的名称匹配。matchImages
: 用于与镜像匹配的字符串列表,以确定是否应调用此提供程序。有关更多信息,请参见下文。defaultCacheDuration
: 如果插件未指定缓存持续时间,kubelet 将在内存中缓存凭据的默认持续时间。apiVersion
: kubelet 和 exec 插件在通信时将使用的 API 版本。
每个凭据提供程序还可以被赋予可选参数和环境变量。请咨询插件实现者以确定给定插件需要哪些参数和环境变量集。
配置镜像匹配
每个凭据提供程序的 matchImages
字段由 kubelet 用于确定是否应为 Pod 使用的给定镜像调用插件。matchImages
中的每个条目都是一个镜像模式,可以包含端口和路径(可选)。可以在域中使用通配符,但不能在端口或路径中使用。通配符支持作为子域,例如 *.k8s.io
或 k8s.*.io
,以及顶级域,例如 k8s.*
。还支持匹配部分子域,例如 app*.k8s.io
。每个通配符只能匹配一个子域段,因此 *.io
不会匹配 *.k8s.io
。
当以下所有条件都满足时,镜像名称和 matchImage
条目之间存在匹配项
- 两者都包含相同数量的域部分,并且每个部分都匹配。
- 匹配镜像的 URL 路径必须是目标镜像 URL 路径的前缀。
- 如果 matchImages 包含端口,则端口也必须与镜像中的端口匹配。
matchImages
模式的示例值如下
123456789.dkr.ecr.us-east-1.amazonaws.com
*.azurecr.io
gcr.io
*.*.registry.io
foo.registry.io:8080/path
下一步
- 阅读有关 kubelet 配置 API (v1) 参考 中的
CredentialProviderConfig
的详细信息。 - 阅读 kubelet 凭据提供程序 API 参考 (v1)。