From c86b8a3e430f57e0e579e2a2b1fb585f40bb7c09 Mon Sep 17 00:00:00 2001
From: Sascha Grunert <sgrunert@redhat.com>
Date: Wed, 2 Jun 2021 11:30:01 +0200
Subject: [PATCH] Add docs about auth differences between Docker and Kubernetes

The interpretation between Docker and Kubernetes varies when comparing
its implementations. This allows different use cases and should be
documented accordingly.

Signed-off-by: Sascha Grunert <sgrunert@redhat.com>
Co-authored-by: Geoffrey Cline <gcline@amazon.com>
Signed-off-by: Sascha Grunert <sgrunert@redhat.com>
---
 content/en/docs/concepts/containers/images.md | 68 +++++++++++++++++++
 .../pull-image-private-registry.md            |  2 +-
 2 files changed, 69 insertions(+), 1 deletion(-)

diff --git a/content/en/docs/concepts/containers/images.md b/content/en/docs/concepts/containers/images.md
index 78323b1302..0dad305c84 100644
--- a/content/en/docs/concepts/containers/images.md
+++ b/content/en/docs/concepts/containers/images.md
@@ -208,6 +208,73 @@ template needs to include the `.docker/config.json` or mount a drive that contai
 All pods will have read access to images in any private registry once private
 registry keys are added to the `.docker/config.json`.
 
+### Interpretation of config.json {#config-json}
+
+The interpretation of `config.json` varies between the original Docker
+implementation and the Kubernetes interpretation. In Docker, the `auths` keys
+can only specify root URLs, whereas Kubernetes allows glob URLs as well as
+prefix-matched paths. This means that a `config.json` like this is valid:
+
+```json
+{
+    "auths": {
+        "*my-registry.io/images": {
+            "auth": "…"
+        }
+    }
+}
+```
+
+The root URL (`*my-registry.io`) is matched by using the following syntax:
+
+```
+pattern:
+    { term }
+
+term:
+    '*'         matches any sequence of non-Separator characters
+    '?'         matches any single non-Separator character
+    '[' [ '^' ] { character-range } ']'
+                character class (must be non-empty)
+    c           matches character c (c != '*', '?', '\\', '[')
+    '\\' c      matches character c
+
+character-range:
+    c           matches character c (c != '\\', '-', ']')
+    '\\' c      matches character c
+    lo '-' hi   matches character c for lo <= c <= hi
+```
+
+Image pull operations would now pass the credentials to the CRI container
+runtime for every valid pattern. For example the following container image names
+would match successfully:
+
+- `my-registry.io/images`
+- `my-registry.io/images/my-image`
+- `my-registry.io/images/another-image`
+- `sub.my-registry.io/images/my-image`
+- `a.sub.my-registry.io/images/my-image`
+
+The kubelet performs image pulls sequentially for every found credential. This
+means, that multiple entries in `config.json` are possible, too:
+
+```json
+{
+    "auths": {
+        "my-registry.io/images": {
+            "auth": "…"
+        },
+        "my-registry.io/images/subpath": {
+            "auth": "…"
+        }
+    }
+}
+```
+
+If now a container specifies an image `my-registry.io/images/subpath/my-image`
+to be pulled, then the kubelet will try to download them from both
+authentication sources if one of them fails.
+
 ### Pre-pulled images
 
 {{< note >}}
@@ -332,3 +399,4 @@ Kubelet will merge any `imagePullSecrets` into a single virtual `.docker/config.
 
 * Read the [OCI Image Manifest Specification](https://github.com/opencontainers/image-spec/blob/master/manifest.md).
 * Learn about [container image garbage collection](/docs/concepts/architecture/garbage-collection/#container-image-garbage-collection).
+* Learn more about [pulling an Image from a Private Registry](/docs/tasks/configure-pod-container/pull-image-private-registry).
diff --git a/content/en/docs/tasks/configure-pod-container/pull-image-private-registry.md b/content/en/docs/tasks/configure-pod-container/pull-image-private-registry.md
index 57c5329b7a..ecb8dd1bfd 100644
--- a/content/en/docs/tasks/configure-pod-container/pull-image-private-registry.md
+++ b/content/en/docs/tasks/configure-pod-container/pull-image-private-registry.md
@@ -28,7 +28,7 @@ docker login
 
 When prompted, enter your Docker username and password.
 
-The login process creates or updates a `config.json` file that holds an authorization token.
+The login process creates or updates a `config.json` file that holds an authorization token. Review [how Kubernetes interprets this file](/docs/concepts/containers/images#config-json). 
 
 View the `config.json` file: