Configure a kubelet image credential provider

    FEATURE STATE:

    Starting from Kubernetes v1.20, the kubelet can dynamically retrieve credentials for a container image registry using exec plugins. The kubelet and the exec plugin communicate through stdio (stdin, stdout, and stderr) using Kubernetes versioned APIs. These plugins allow the kubelet to request credentials for a container registry dynamically as opposed to storing static credentials on disk. For example, the plugin may talk to a local metadata server to retrieve short-lived credentials for an image that is being pulled by the kubelet.

    You may be interested in using this capability if any of the below are true:

    • API calls to a cloud provider service are required to retrieve authentication information for a registry.
    • Credentials have short expiration times and requesting new credentials frequently is required.
    • You need a Kubernetes cluster with nodes that support kubelet credential provider plugins. This support is available in Kubernetes 1.26; Kubernetes v1.24 and v1.25 included this as a beta feature, enabled by default.
    • A working implementation of a credential provider exec plugin. You can build your own plugin or use one provided by cloud providers.

    Your Kubernetes server must be version v1.26. To check the version, enter kubectl version.

    A credential provider plugin is an executable binary that will be run by the kubelet. Ensure that the plugin binary exists on every node in your cluster and stored in a known directory. The directory will be required later when configuring kubelet flags.

    In order to use this feature, the kubelet expects two flags to be set:

    • --image-credential-provider-config - the path to the credential provider plugin config file.
    • --image-credential-provider-bin-dir - the path to the directory where credential provider plugin binaries are located.

    The providers field is a list of enabled plugins used by the kubelet. Each entry has a few required fields:

    • name: the name of the plugin which MUST match the name of the executable binary that exists in the directory passed into --image-credential-provider-bin-dir.
    • matchImages: a list of strings used to match against images in order to determine if this provider should be invoked. More on this below.
    • : the default duration the kubelet will cache credentials in-memory if a cache duration was not specified by the plugin.
    • apiVersion: the API version that the kubelet and the exec plugin will use when communicating.

    Each credential provider can also be given optional args and environment variables as well. Consult the plugin implementors to determine what set of arguments and environment variables are required for a given plugin.

    Configure image matching

    The matchImages field for each credential provider is used by the kubelet to determine whether a plugin should be invoked for a given image that a Pod is using. Each entry in matchImages is an image 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 .

    • The URL path of match image must be a prefix of the target image URL path.
    • If the imageMatch contains a port, then the port must match in the image as well.

    Some example values of matchImages patterns are:

    • 123456789.dkr.ecr.us-east-1.amazonaws.com
    • *.azurecr.io
    • gcr.io
    • *.*.registry.io
    • foo.registry.io:8080/path