add: v1alpha4 add registry create proxy config + documentation

CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## Unreleased
+
+### Added
+
+- Support for pull-through registry (#1075)
+  - In command `k3d registry create`
+    - e.g. `k3d registry create --proxy-remote-url https://registry-1.docker.io -p 5000 -v /tmp/registry:/var/lib/registry`
+  - In config file:
+
+      ```yaml
+      # ...
+      registries:
+        create:
+          name: docker-io # name of the registry container
+          proxy:
+            remoteURL: https://registry-1.docker.io # proxy DockerHub
+          volumes:
+            - /tmp/reg:/var/lib/registry # persist data locally in /tmp/reg
+        config: | # tell K3s to use this registry when pulling from DockerHub
+          mirrors:
+            "docker.io":
+              endpoint:
+                - http://docker-io:5000
+      ```
+
+  - See registry documentation
+
 ## v5.4.2 - 04.06.2022
 
 ### Added

docgen/go.mod

@@ -3,9 +3,8 @@ module github.com/k3d-io/k3d/docgen
 go 1.16
 
 require (
-	github.com/google/gofuzz v1.2.0 // indirect
 	github.com/k3d-io/k3d/v5 v5.0.0-00010101000000-000000000000
-	github.com/spf13/cobra v1.3.0
+	github.com/spf13/cobra v1.4.0
 )
 
 replace github.com/k3d-io/k3d/v5 => /PATH/TO/YOUR/REPO/DIRECTORY

docs/usage/commands/k3d_registry_create.md

@@ -13,12 +13,16 @@ k3d registry create NAME [flags]
 ### Options
 
 ```
-      --default-network string   Specify the network connected to the registry (default "bridge")
-  -h, --help                     help for create
-  -i, --image string             Specify image used for the registry (default "docker.io/library/registry:2")
-      --no-help                  Disable the help text (How-To use the registry)
-  -p, --port [HOST:]HOSTPORT     Select which port the registry should be listening on on your machine (localhost) (Format: [HOST:]HOSTPORT)
-                                  - Example: `k3d registry create --port 0.0.0.0:5111` (default "random")
+      --default-network string    Specify the network connected to the registry (default "bridge")
+  -h, --help                      help for create
+  -i, --image string              Specify image used for the registry (default "docker.io/library/registry:2")
+      --no-help                   Disable the help text (How-To use the registry)
+  -p, --port [HOST:]HOSTPORT      Select which port the registry should be listening on on your machine (localhost) (Format: [HOST:]HOSTPORT)
+                                   - Example: `k3d registry create --port 0.0.0.0:5111` (default "random")
+      --proxy-password string     Specify the password of the proxied remote registry
+      --proxy-remote-url string   Specify the url of the proxied remote registry
+      --proxy-username string     Specify the username of the proxied remote registry
+  -v, --volume [SOURCE:]DEST      Mount volumes into the registry node (Format: [SOURCE:]DEST
 ```
 
 ### Options inherited from parent commands

docs/usage/configfile.md

@@ -82,6 +82,12 @@ registries: # define how registries should be created or used
     name: registry.localhost
     host: "0.0.0.0"
     hostPort: "5000"
+    proxy: # omit this to have a "normal" registry, set this to create a registry proxy (pull-through cache)
+      remoteURL: https://registry-1.docker.io # mirror the DockerHub registry
+      username: "" # unauthenticated
+      password: "" # unauthenticated
+    volumes:
+      - /some/path:/var/lib/registry # persist registry data locally
   use:
     - k3d-myotherregistry:5000 # some other k3d-managed registry; same as `--registry-use 'k3d-myotherregistry:5000'`
   config: | # define contents of the `registries.yaml` file (or reference a file); same as `--registry-config /path/to/config.yaml`

docs/usage/registries.md

@@ -132,7 +132,7 @@ Now you have a few options, including the following three:
 
 ### Using your own (not k3d-managed) local registry
 
-*We recommend using a k3d-managed registry, as it plays nicely together with k3d clusters, but here's also a guide to create your own (not k3d-managed) registry, if you need features or customizations, that k3d does not provide:*
+_We recommend using a k3d-managed registry, as it plays nicely together with k3d clusters, but here's also a guide to create your own (not k3d-managed) registry, if you need features or customizations, that k3d does not provide:_
 
 ??? nonk3dregistry "Using your own (not k3d-managed) local registry"
 
@@ -214,3 +214,64 @@ Then you should check that the pod is running with `kubectl get pods -l "app=ngi
 3. push it: `#!bash docker push k3d-registry.localhost:12345/testimage:local`
 4. Use kubectl to create a new pod in your cluster using that image to see, if the cluster can pull from the new registry: `#!bash kubectl run --image k3d-registry.localhost:12345/testimage:local testimage --command -- tail -f /dev/null`
    - (creates a container that will not do anything but keep on running)
+
+## Creating a registry proxy / pull-through registry
+
+1. Create a pull-through registry
+
+    ```bash
+    k3d registry create docker-io `# Create a registry named k3d-docker-io` \
+      -p 5000 `# listening on local host port 5000` \ 
+      --proxy-remote-url https://registry-1.docker.io `# let it mirror the Docker Hub registry` \
+      -v ~/.local/share/docker-io-registry:/var/lib/registry `# also persist the downloaded images on the device outside the container`
+    ```
+
+2. Create `registry.yaml`
+
+    ```yaml
+    mirrors:
+      "docker.io":
+        endpoint:
+          - http://k3d-docker-io:5000
+    ```
+
+3. Create a cluster and using the pull-through cache
+
+    ```bash
+    k3d cluster create cluster01 --registry-use k3d-docker-io:5000 --registry-config registry.yml
+    ```
+
+4. After cluster01 ready, create another cluster with the same registry or rebuild the cluster, it will use the already locally cached images.
+
+    ```bash
+    k3d cluster create cluster02 --registry-use k3d-docker-io:5000 --registry-config registry.yml
+    ```
+
+### Creating a registry proxy / pull-through registry via configfile
+
+1. Create a config file, e.g. `/home/me/test-regcache.yaml`
+
+    ```yaml
+    apiVersion: k3d.io/v1alpha4
+    kind: Simple
+    metadata:
+      name: test-regcache
+    registries:
+      create:
+        name: docker-io # name of the registry container
+        proxy:
+          remoteURL: https://registry-1.docker.io # proxy DockerHub
+        volumes:
+          - /tmp/reg:/var/lib/registry # persist data locally in /tmp/reg
+      config: | # tell K3s to use this registry when pulling from DockerHub
+        mirrors:
+          "docker.io":
+            endpoint:
+              - http://docker-io:5000
+    ```
+
+2. Create cluster from config:
+
+    ```bash
+    k3d cluster create -c /home/me/test-regcache.yaml
+    ```

pkg/config/transform.go

@@ -324,6 +324,10 @@ func TransformSimpleToClusterConfig(ctx context.Context, runtime runtimes.Runtim
 			Host:         regName,
 			Image:        image,
 			ExposureOpts: *regPort,
+			Volumes:      simpleConfig.Registries.Create.Volumes,
+			Options: k3d.RegistryOptions{
+				Proxy: simpleConfig.Registries.Create.Proxy,
+			},
 		}
 	}
 

pkg/config/v1alpha4/schema.json

@@ -301,6 +301,33 @@
                 "myregistry/registry:2"
               ],
               "default": "docker.io/library/registry:2"
+            },
+            "proxy": {
+              "type": "object",
+              "properties": {
+                "remoteURL": {
+                  "type": "string",
+                  "examples": [
+                    "https://registry-1.docker.io"
+                  ]
+                },
+                "username": {
+                  "type": "string"
+                },
+                "password": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": false
+            },
+            "volumes": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "examples": [
+                "/tmp/registry:/var/lib/registry"
+              ]
             }
           },
           "additionalProperties": false

pkg/config/v1alpha4/types.go

@@ -82,10 +82,12 @@ type K3sArgWithNodeFilters struct {
 }
 
 type SimpleConfigRegistryCreateConfig struct {
-	Name     string `mapstructure:"name" yaml:"name,omitempty" json:"name,omitempty"`
-	Host     string `mapstructure:"host" yaml:"host,omitempty" json:"host,omitempty"`
-	HostPort string `mapstructure:"hostPort" yaml:"hostPort,omitempty" json:"hostPort,omitempty"`
-	Image    string `mapstructure:"image" yaml:"image,omitempty" json:"image,omitempty"`
+	Name     string            `mapstructure:"name" yaml:"name,omitempty" json:"name,omitempty"`
+	Host     string            `mapstructure:"host" yaml:"host,omitempty" json:"host,omitempty"`
+	HostPort string            `mapstructure:"hostPort" yaml:"hostPort,omitempty" json:"hostPort,omitempty"`
+	Image    string            `mapstructure:"image" yaml:"image,omitempty" json:"image,omitempty"`
+	Proxy    k3d.RegistryProxy `mapstructure:"proxy" yaml:"proxy,omitempty" json:"proxy,omitempty"`
+	Volumes  []string          `mapstructure:"volumes" yaml:"volumes,omitempty" json:"volumes,omitempty"`
 }
 
 // SimpleConfigOptionsKubeconfig describes the set of options referring to the kubeconfig during cluster creation.