[zh-cn]sync kubelet-credential-provide

Signed-off-by: xin.li <xin.li@daocloud.io>

Author: my-git9

content/zh-cn/docs/tasks/administer-cluster/kubelet-credential-provider.md

@@ -48,17 +48,79 @@ This guide demonstrates how to configure the kubelet's image credential provider
 
 本指南演示如何配置 kubelet 的镜像凭据提供程序插件机制。
 
+<!--
+## Service Account Token for Image Pulls
+-->
+## 使用服务帐号令牌拉取镜像   {#service-account-token-for-image-pulls}
+
+{{< feature-state feature_gate_name="KubeletServiceAccountTokenForCredentialProviders" >}}
+
+<!--
+Starting from Kubernetes v1.33,
+the kubelet can be configured to send a service account token
+bound to the pod for which the image pull is being performed
+to the credential provider plugin.
+
+This allows the plugin to exchange the token for credentials
+to access the image registry.
+-->
+从 Kubernetes v1.33 开始，
+可以配置 kubelet 在为 Pod 执行镜像拉取时发送一个与该 Pod
+绑定的服务账号令牌给凭据提供者插件。
+
+这允许插件用该令牌交换访问镜像仓库的凭据。
+
+<!--
+To enable this feature,
+the `KubeletServiceAccountTokenForCredentialProviders` feature gate
+must be enabled on the kubelet,
+and the `tokenAttributes` field must be set
+in the `CredentialProviderConfig` file for the plugin.
+
+The `tokenAttributes` field contains information
+about the service account token that will be passed to the plugin,
+including the intended audience for the token
+and whether the plugin requires the pod to have a service account.
+-->
+要启用此特性，
+必须在 kubelet 上启用 `KubeletServiceAccountTokenForCredentialProviders` 特性门控，
+并且必须在插件的 `CredentialProviderConfig` 文件中设置 `tokenAttributes` 字段。
+
+`tokenAttributes` 字段包含将传递给插件的服务帐号令牌的信息，
+包括令牌的预期受众和插件是否要求 Pod 拥有服务帐号。
+
+<!--
+Using service account token credentials can enable the following use-cases:
+
+* Avoid needing a kubelet/node-based identity to pull images from a registry.
+* Allow workloads to pull images based on their own runtime identity
+without long-lived/persisted secrets.
+-->
+使用服务帐号令牌凭据可以启用以下用例：
+
+* 避免需要基于 kubelet/节点的身份从镜像仓库拉取镜像。
+* 允许工作负载根据其自身的运行时身份拉取镜像，
+  而无需长期存在的/持久化的 Secret。
+
 ## {{% heading "prerequisites" %}}
 
 <!-- 
 * You need a Kubernetes cluster with nodes that support kubelet credential
   provider plugins. This support is available in Kubernetes {{< skew currentVersion >}};
   Kubernetes v1.24 and v1.25 included this as a beta feature, enabled by default.
+* If you are configuring a credential provider plugin
+  that requires the service account token,
+  you need a Kubernetes cluster with nodes running Kubernetes v1.33 or later
+  and the `KubeletServiceAccountTokenForCredentialProviders` feature gate
+  enabled on the kubelet.
 * A working implementation of a credential provider exec plugin. You can build your own plugin or use one provided by cloud providers.
 -->
 * 你需要一个 Kubernetes 集群，其节点支持 kubelet 凭据提供程序插件。
   这种支持在 Kubernetes {{< skew currentVersion >}} 中可用；
   Kubernetes v1.24 和 v1.25 将此作为 Beta 特性包含在内，默认启用。
+* 如果你正在配置需要服务帐号令牌的凭据提供者插件，
+  你需要一个运行 Kubernetes v1.33 或更高版本的 Kubernetes 集群，
+  并且在 kubelet 上启用了 `KubeletServiceAccountTokenForCredentialProviders` 特性门控。
 * 凭据提供程序 exec 插件的一种可用的实现。你可以构建自己的插件或使用云提供商提供的插件。
 
 {{< version-check >}}
@@ -106,6 +168,112 @@ kubelet 会读取通过 `--image-credential-provider-config` 设定的配置文
 如果你正在使用基于 [ECR-based 插件](https://github.com/kubernetes/cloud-provider-aws/tree/master/cmd/ecr-credential-provider)，
 这里有个样例配置文件你可能最终会使用到：
 
+<!--
+```yaml
+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
+
+    # tokenAttributes is the configuration for the service account token that will be passed to the plugin.
+    # The credential provider opts in to using service account tokens for image pull by setting this field.
+    # if this field is set without the `KubeletServiceAccountTokenForCredentialProviders` feature gate enabled, 
+    # kubelet will fail to start with invalid configuration error.
+    # +optional
+    tokenAttributes:
+      # serviceAccountTokenAudience is the intended audience for the projected service account token.
+      # +required
+      serviceAccountTokenAudience: "<audience for the token>"
+      # requireServiceAccount indicates whether the plugin requires the pod to have a service account.
+      # If set to true, kubelet will only invoke the plugin if the pod has a service account.
+      # If set to false, kubelet will invoke the plugin even if the pod does not have a service account
+      # and will not include a token in the CredentialProviderRequest. This is useful for plugins
+      # that are used to pull images for pods without service accounts (e.g., static pods).
+      # +required
+      requireServiceAccount: true
+      # requiredServiceAccountAnnotationKeys is the list of annotation keys that the plugin is interested in 
+      # and that are required to be present in the service account.
+      # The keys defined in this list will be extracted from the corresponding service account and passed 
+      # to the plugin as part of the CredentialProviderRequest. If any of the keys defined in this list 
+      # are not present in the service account, kubelet will not invoke the plugin and will return an error. 
+      # This field is optional and may be empty. Plugins may use this field to extract additional information 
+      # required to fetch credentials or allow workloads to opt in to using service account tokens for image pull.
+      # If non-empty, requireServiceAccount must be set to true.
+      # The keys defined in this list must be unique and not overlap with the keys defined in the
+      # optionalServiceAccountAnnotationKeys list.
+      # +optional
+      requiredServiceAccountAnnotationKeys:
+      - "example.com/required-annotation-key-1"
+      - "example.com/required-annotation-key-2"
+      # optionalServiceAccountAnnotationKeys is the list of annotation keys that the plugin is interested in 
+      # and that are optional to be present in the service account.
+      # The keys defined in this list will be extracted from the corresponding service account and passed 
+      # to the plugin as part of the CredentialProviderRequest. The plugin is responsible for validating the 
+      # existence of annotations and their values. This field is optional and may be empty. 
+      # Plugins may use this field to extract additional information required to fetch credentials.
+      # The keys defined in this list must be unique and not overlap with the keys defined in the
+      # requiredServiceAccountAnnotationKeys list.
+      # +optional
+      optionalServiceAccountAnnotationKeys:
+      - "example.com/optional-annotation-key-1"
+      - "example.com/optional-annotation-key-2"
+```
+-->
 ```yaml
 apiVersion: kubelet.config.k8s.io/v1
 kind: CredentialProviderConfig
@@ -165,6 +333,44 @@ providers:
     env:
       - name: AWS_PROFILE
         value: example_profile
+
+    # tokenAttributes 是将传递给插件的服务账号令牌的配置。
+    # 凭证提供者通过设置此字段选择使用服务账号令牌进行镜像拉取。
+    # 如果在未启用 `KubeletServiceAccountTokenForCredentialProviders` 特性门控的情况下设置了此字段，
+    # kubelet 将因无效配置错误而无法启动。
+    # 可选
+    tokenAttributes:
+      # serviceAccountTokenAudience 是 projected service account token 的预期受众。
+      # 必需
+      serviceAccountTokenAudience: "<audience for the token>"
+      # requireServiceAccount 指示插件是否需要 Pod 拥有服务帐号。
+      # 如果设置为 true，kubelet 仅在 Pod 拥有服务账号时才会调用插件。
+      # 如果设置为 false，即使 Pod 没有服务账号，kubelet 也会调用插件，
+      # 并且不会在 CredentialProviderRequest 中包含令牌。这对于用于拉取没有服务账号的 Pod（例如静态 Pod）镜像的插件非常有用。
+      # 必需
+      requireServiceAccount: true
+      # requiredServiceAccountAnnotationKeys 是插件感兴趣的注解键列表，
+      # 并且这些键需要存在于服务帐号中。
+      # 在此列表中定义的键将从相应的服务帐号中提取，并作为 CredentialProviderRequest 的一部分传递给插件。
+      # 如果此列表中定义的任何一个键不存在于 service account 中，kubelet 将不会调用插件并返回错误。
+      # 此字段是可选的，可以为空。插件可以使用此字段提取获取凭据所需的额外信息，
+      # 或允许工作负载选择使用服务帐号令牌进行镜像拉取。
+      # 如果非空，则 requireServiceAccount 必须设置为 true。
+      # 此列表中定义的键必须唯一且不与 optionalServiceAccountAnnotationKeys 列表中定义的键重叠。
+      # 可选
+      requiredServiceAccountAnnotationKeys:
+      - "example.com/required-annotation-key-1"
+      - "example.com/required-annotation-key-2"
+      # optionalServiceAccountAnnotationKeys 是插件感兴趣的注解键列表，
+      # 并且这些键在服务帐号中是可选存在的。
+      # 在此列表中定义的键将从相应的 service account 中提取，并作为 CredentialProviderRequest 的一部分传递给插件。
+      # 插件负责验证注解及其值的存在性。此字段是可选的，可以为空。
+      # 插件可以使用此字段提取获取凭据所需的额外信息。
+      # 此列表中定义的键必须唯一且不与 requiredServiceAccountAnnotationKeys 列表中定义的键重叠。
+      # 可选
+      optionalServiceAccountAnnotationKeys:
+      - "example.com/optional-annotation-key-1"
+      - "example.com/optional-annotation-key-2"
 ```
 
 <!-- 
@@ -193,6 +399,46 @@ Consult the plugin implementors to determine what set of arguments and environme
 每个凭据提供程序也可以被赋予可选的参数和环境变量。
 你可以咨询插件实现者以确定给定插件需要哪些参数和环境变量集。
 
+<!--
+If you are using the KubeletServiceAccountTokenForCredentialProviders feature gate
+and configuring the plugin to use the service account token
+by setting the tokenAttributes field,
+the following fields are required:
+-->
+如果你正在使用 KubeletServiceAccountTokenForCredentialProviders 特性门控
+并且通过设置 tokenAttributes 字段配置插件使用服务帐号令牌，
+那么需要以下字段：
+
+<!--
+* `serviceAccountTokenAudience`:
+  the intended audience for the projected service account token.
+  This cannot be the empty string.
+* `requireServiceAccount`:
+  whether the plugin requires the pod to have a service account.
+  * If set to `true`, kubelet will only invoke the plugin
+if the pod has a service account.
+  * If set to `false`, kubelet will invoke the plugin
+even if the pod does not have a service account
+and will not include a token in the `CredentialProviderRequest`.
+
+This is useful for plugins that are used
+to pull images for pods without service accounts
+(e.g., static pods).
+-->
+* `serviceAccountTokenAudience`：
+  预期的投射服务帐号令牌的受众。
+  这不能是空字符串。
+
+* `requireServiceAccount`：
+  插件是否要求 Pod 拥有服务帐号。
+- 如果设置为 `true`，kubelet 只会在 Pod 拥有 service account 时
+  调用插件。
+- 如果设置为 `false`，即使 Pod 没有服务帐号，
+  kubelet 也会调用插件，并且不会在 `CredentialProviderRequest` 中包含令牌。
+
+这对于用于拉取没有服务帐号的 Pod 的镜像的插件非常有用
+（例如，静态 Pod）。
+
 <!-- 
 #### Configure image matching