Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update docs for kubelet credentials provider GA #38139

Merged
merged 1 commit into from
Dec 6, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions content/en/docs/concepts/containers/images.md
Original file line number Diff line number Diff line change
Expand Up @@ -167,6 +167,9 @@ Credentials can be provided in several ways:
- Configuring Nodes to Authenticate to a Private Registry
- all pods can read any configured private registries
- requires node configuration by cluster administrator
- Kubelet Credential Provider to dynamically fetch credentials for private registries
- kubelet can be configured to use credential provider exec plugin
for the respective private registry.
- Pre-pulled Images
- all pods can use any images cached on a node
- requires root access to all nodes to set up
Expand All @@ -187,6 +190,18 @@ For an example of configuring a private container image registry, see the
[Pull an Image from a Private Registry](/docs/tasks/configure-pod-container/pull-image-private-registry)
task. That example uses a private registry in Docker Hub.

### Kubelet credential provider for authenticated image pulls {#kubelet-credential-provider}

{{< note >}}
This approach is especially suitable when kubelet needs to fetch registry credentials dynamically.
Most commonly used for registries provided by cloud providers where auth tokens are short-lived.
{{< /note >}}

You can configure the kubelet to invoke a plugin binary to dynamically fetch registry credentials for a container image.
This is the most robust and versatile way to fetch credentials for private registries, but also requires kubelet-level configuration to enable.

See [Configure a kubelet image credential provider](/docs/tasks/administer-cluster/kubelet-credential-provider/) for more details.

### Interpretation of config.json {#config-json}

The interpretation of `config.json` varies between the original Docker
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -122,8 +122,6 @@ For a reference to old feature gates that are removed, please refer to
| `JobTrackingWithFinalizers` | `false` | Beta | 1.23 | 1.24 |
| `JobTrackingWithFinalizers` | `true` | Beta | 1.25 | |
| `KMSv2` | `false` | Alpha | 1.25 | |
| `KubeletCredentialProviders` | `false` | Alpha | 1.20 | 1.23 |
| `KubeletCredentialProviders` | `true` | Beta | 1.24 | |
| `KubeletInUserNamespace` | `false` | Alpha | 1.22 | |
| `KubeletPodResources` | `false` | Alpha | 1.13 | 1.14 |
| `KubeletPodResources` | `true` | Beta | 1.15 | |
Expand Down Expand Up @@ -303,6 +301,9 @@ For a reference to old feature gates that are removed, please refer to
| `JobTrackingWithFinalizers` | `false` | Beta | 1.23 | 1.24 |
| `JobTrackingWithFinalizers` | `true` | Beta | 1.25 | 1.25 |
| `JobTrackingWithFinalizers` | `true` | GA | 1.26 | - |
| `KubeletCredentialProviders` | `false` | Alpha | 1.20 | 1.23 |
| `KubeletCredentialProviders` | `true` | Beta | 1.24 | 1.25 |
| `KubeletCredentialProviders` | `true` | GA | 1.26 | - |
| `LegacyServiceAccountTokenNoAutoGeneration` | `true` | Beta | 1.24 | 1.25 |
| `LegacyServiceAccountTokenNoAutoGeneration` | `true` | GA | 1.26 | - |
| `LocalStorageCapacityIsolation` | `false` | Alpha | 1.7 | 1.9 |
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,10 @@ reviewers:
- cheftako
description: Configure the kubelet's image credential provider plugin
content_type: task
min-kubernetes-server-version: v1.26
---

{{< feature-state for_k8s_version="v1.24" state="beta" >}}
{{< feature-state for_k8s_version="v1.26" state="stable" >}}

<!-- overview -->

Expand All @@ -27,10 +28,13 @@ This guide demonstrates how to configure the kubelet's image credential provider

## {{% heading "prerequisites" %}}

* 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.
* You need a Kubernetes cluster with nodes that support kubelet credential
provider plugins. This support is available in Kubernetes {{< skew currentVersion >}};
ndixita marked this conversation as resolved.
Show resolved Hide resolved
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.

{{< version-check >}}

<!-- steps -->

## Installing Plugins on Nodes
Expand All @@ -52,9 +56,9 @@ should be invoked for which container images. Here's an example configuration fi
[ECR](https://aws.amazon.com/ecr/)-based plugin:

```yaml
apiVersion: kubelet.config.k8s.io/v1alpha1
apiVersion: kubelet.config.k8s.io/v1
kind: CredentialProviderConfig
# providers is a list of credential provider plugins that will be enabled by the kubelet.
# 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
Expand All @@ -74,7 +78,7 @@ providers:
# 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 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.
Expand All @@ -98,8 +102,8 @@ providers:
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/v1alpha1
apiVersion: credentialprovider.kubelet.k8s.io/v1alpha1
# - credentialprovider.kubelet.k8s.io/v1
apiVersion: credentialprovider.kubelet.k8s.io/v1
# Arguments to pass to the command when executing it.
# +optional
args:
Expand Down Expand Up @@ -151,6 +155,6 @@ Some example values of `matchImages` patterns are:
## {{% heading "whatsnext" %}}

* Read the details about `CredentialProviderConfig` in the
[kubelet configuration API (v1alpha1) reference](/docs/reference/config-api/kubelet-config.v1alpha1/).
* Read the [kubelet credential provider API reference (v1alpha1)](/docs/reference/config-api/kubelet-credentialprovider.v1alpha1/).
[kubelet configuration API (v1) reference](/docs/reference/config-api/kubelet-config.v1/).
* Read the [kubelet credential provider API reference (v1)](/docs/reference/config-api/kubelet-credentialprovider.v1/).

1 change: 1 addition & 0 deletions static/_redirects
Original file line number Diff line number Diff line change
Expand Up @@ -316,6 +316,7 @@
/docs/tasks/kubectl/install/ /docs/tasks/tools/ 301
/docs/tasks/tools/install-kubectl/ /docs/tasks/tools/ 301
/docs/tasks/kubectl/list-all-running-container-images/ /docs/tasks/access-application-cluster/list-all-running-container-images/ 301
/docs/tasks/kubelet-credential-provider/kubelet-credential-provider/ /docs/tasks/administer-cluster/kubelet-credential-provider/ 301
/docs/tasks/manage-stateful-set/debugging-a-statefulset/ /docs/tasks/debug/debug-application/debug-statefulset/ 301
/docs/tasks/manage-stateful-set/delete-pods/ /docs/tasks/run-application/delete-stateful-set/ 301
/docs/tasks/manage-stateful-set/deleting-a-statefulset/ /docs/tasks/run-application/delete-stateful-set/ 301
Expand Down