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.
    • The kubelet image credential provider is introduced in v1.20 as an alpha feature. As with other alpha features, a feature gate KubeletCredentialProviders must be enabled on only the kubelet for the feature to work.
    • A working implementation of a credential provider exec plugin. You can build your own plugin or use one provided by cloud providers.

    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 configuration file passed into --image-credential-provider-config is read by the kubelet to determine which exec plugins should be invoked for which container images. Here’s an example configuration file you may end up using if you are using the -based plugin:

    • 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.
    • : a list of strings used to match against images in order to determine if this provider should be invoked. More on this below.
    • defaultCacheDuration: the default duration the kubelet will cache credentials in-memory if a cache duration was not specified by the plugin.

    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 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 name and a matchImage entry when all of the below are true:

    • Both contain the same number of domain parts and each part matches.
    • 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.
    • 123456789.dkr.ecr.us-east-1.amazonaws.com
    • *.azurecr.io
    • gcr.io