fix(registry): image name parsing behavior (#1526)

Co-authored-by: nils måsén <[email protected]>

Author: Pwuts

docs/private-registries.md

@@ -23,19 +23,29 @@ password `auth` string:
 ```
 
 `<REGISTRY_NAME>` needs to be replaced by the name of your private registry
-(e.g., `my-private-registry.example.org`)
-
-!!! important "Using private images on docker hub"
-    When using private images on docker hub, the containers beeing watched needs to use the full image name, including the repository prefix `index.docker.io`.
-    So instead of
-    ```
-    docker run -d myuser/myimage
-    ```
-    you would run it as
-    ```
-    docker run -d index.docker.io/myuser/myimage
-    ```
-
+(e.g., `my-private-registry.example.org`).
+
+!!! info "Using private images on Docker Hub"
+    To access private repositories on Docker Hub,
+    `<REGISTRY_NAME>` should be `https://index.docker.io/v1/`.
+    In this special case, the registry domain does not have to be specified
+    in `docker run` or `docker-compose`. Like Docker, Watchtower will use the
+    Docker Hub registry and its credentials when no registry domain is specified.
+    
+    <sub>Watchtower will recognize credentials with `<REGISTRY_NAME>` `index.docker.io`,
+    but the Docker CLI will not.</sub>
+
+!!! important "Using a private registry on a local host"
+    To use a private registry hosted locally, make sure to correctly specify the registry host
+    in both `config.json` and the `docker run` command or `docker-compose` file.
+    Valid hosts are `localhost[:PORT]`, `HOST:PORT`,
+    or any multi-part `domain.name` or IP-address with or without a port.
+    
+    Examples:
+    * `localhost` -> `localhost/myimage`
+    * `127.0.0.1` -> `127.0.0.1/myimage:mytag`
+    * `host.domain` -> `host.domain/myorganization/myimage`
+    * `other-lan-host:80` -> `other-lan-host:80/imagename:latest`
 
 The required `auth` string can be generated as follows:
 
@@ -75,7 +85,7 @@ When creating the watchtower container via docker-compose, use the following lin
 version: "3.4"
 services:
   watchtower:
-    image: index.docker.io/containrrr/watchtower:latest
+    image: containrrr/watchtower:latest
     volumes:
       - /var/run/docker.sock:/var/run/docker.sock
       - <PATH_TO_HOME_DIR>/.docker/config.json:/config.json

docs/usage-overview.md

@@ -48,14 +48,14 @@ docker run -d \
 
 If you mount the config file as described above, be sure to also prepend the URL for the registry when starting up your
 watched image (you can omit the https://). Here is a complete docker-compose.yml file that starts up a docker container
-from a private repo at Docker Hub and monitors it with watchtower. Note the command argument changing the interval to
-30s rather than the default 24 hours.
+from a private repo on the GitHub Registry and monitors it with watchtower. Note the command argument changing the interval
+to 30s rather than the default 24 hours.
 
 ```yaml
 version: "3"
 services:
   cavo:
-    image: index.docker.io/<org>/<image>:<tag>
+    image: ghcr.io/<org>/<image>:<tag>
     ports:
       - "443:3443"
       - "80:3080"

pkg/registry/auth/auth.go

@@ -4,14 +4,14 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
-	"io/ioutil"
+	"io"
 	"net/http"
 	"net/url"
 	"strings"
 
 	"github.com/containrrr/watchtower/pkg/registry/helpers"
 	"github.com/containrrr/watchtower/pkg/types"
-	"github.com/docker/distribution/reference"
+	ref "github.com/docker/distribution/reference"
 	"github.com/sirupsen/logrus"
 )
 
@@ -20,13 +20,13 @@ const ChallengeHeader = "WWW-Authenticate"
 
 // GetToken fetches a token for the registry hosting the provided image
 func GetToken(container types.Container, registryAuth string) (string, error) {
-	var err error
-	var URL url.URL
-
-	if URL, err = GetChallengeURL(container.ImageName()); err != nil {
+	normalizedRef, err := ref.ParseNormalizedNamed(container.ImageName())
+	if err != nil {
 		return "", err
 	}
-	logrus.WithField("URL", URL.String()).Debug("Building challenge URL")
+
+	URL := GetChallengeURL(normalizedRef)
+	logrus.WithField("URL", URL.String()).Debug("Built challenge URL")
 
 	var req *http.Request
 	if req, err = GetChallengeRequest(URL); err != nil {
@@ -55,7 +55,7 @@ func GetToken(container types.Container, registryAuth string) (string, error) {
 		return fmt.Sprintf("Basic %s", registryAuth), nil
 	}
 	if strings.HasPrefix(challenge, "bearer") {
-		return GetBearerHeader(challenge, container.ImageName(), registryAuth)
+		return GetBearerHeader(challenge, normalizedRef, registryAuth)
 	}
 
 	return "", errors.New("unsupported challenge type from registry")
@@ -73,12 +73,9 @@ func GetChallengeRequest(URL url.URL) (*http.Request, error) {
 }
 
 // GetBearerHeader tries to fetch a bearer token from the registry based on the challenge instructions
-func GetBearerHeader(challenge string, img string, registryAuth string) (string, error) {
+func GetBearerHeader(challenge string, imageRef ref.Named, registryAuth string) (string, error) {
 	client := http.Client{}
-	if strings.Contains(img, ":") {
-		img = strings.Split(img, ":")[0]
-	}
-	authURL, err := GetAuthURL(challenge, img)
+	authURL, err := GetAuthURL(challenge, imageRef)
 
 	if err != nil {
 		return "", err
@@ -103,7 +100,7 @@ func GetBearerHeader(challenge string, img string, registryAuth string) (string,
 		return "", err
 	}
 
-	body, _ := ioutil.ReadAll(authResponse.Body)
+	body, _ := io.ReadAll(authResponse.Body)
 	tokenResponse := &types.TokenResponse{}
 
 	err = json.Unmarshal(body, tokenResponse)
@@ -115,7 +112,7 @@ func GetBearerHeader(challenge string, img string, registryAuth string) (string,
 }
 
 // GetAuthURL from the instructions in the challenge
-func GetAuthURL(challenge string, img string) (*url.URL, error) {
+func GetAuthURL(challenge string, imageRef ref.Named) (*url.URL, error) {
 	loweredChallenge := strings.ToLower(challenge)
 	raw := strings.TrimPrefix(loweredChallenge, "bearer")
 
@@ -141,53 +138,25 @@ func GetAuthURL(challenge string, img string) (*url.URL, error) {
 	q := authURL.Query()
 	q.Add("service", values["service"])
 
-	scopeImage := GetScopeFromImageName(img, values["service"])
+	scopeImage := ref.Path(imageRef)
 
 	scope := fmt.Sprintf("repository:%s:pull", scopeImage)
-	logrus.WithFields(logrus.Fields{"scope": scope, "image": img}).Debug("Setting scope for auth token")
+	logrus.WithFields(logrus.Fields{"scope": scope, "image": imageRef.Name()}).Debug("Setting scope for auth token")
 	q.Add("scope", scope)
 
 	authURL.RawQuery = q.Encode()
 	return authURL, nil
 }
 
-// GetScopeFromImageName normalizes an image name for use as scope during auth and head requests
-func GetScopeFromImageName(img, svc string) string {
-	parts := strings.Split(img, "/")
-
-	if len(parts) > 2 {
-		if strings.Contains(svc, "docker.io") {
-			return fmt.Sprintf("%s/%s", parts[1], strings.Join(parts[2:], "/"))
-		}
-		return strings.Join(parts, "/")
-	}
-
-	if len(parts) == 2 {
-		if strings.Contains(parts[0], "docker.io") {
-			return fmt.Sprintf("library/%s", parts[1])
-		}
-		return strings.Replace(img, svc+"/", "", 1)
-	}
-
-	if strings.Contains(svc, "docker.io") {
-		return fmt.Sprintf("library/%s", parts[0])
-	}
-	return img
-}
-
-// GetChallengeURL creates a URL object based on the image info
-func GetChallengeURL(img string) (url.URL, error) {
-
-	normalizedNamed, _ := reference.ParseNormalizedNamed(img)
-	host, err := helpers.NormalizeRegistry(normalizedNamed.String())
-	if err != nil {
-		return url.URL{}, err
-	}
+// GetChallengeURL returns the URL to check auth requirements
+// for access to a given image
+func GetChallengeURL(imageRef ref.Named) url.URL {
+	host, _ := helpers.GetRegistryAddress(imageRef.Name())
 
 	URL := url.URL{
 		Scheme: "https",
 		Host:   host,
 		Path:   "/v2/",
 	}
-	return URL, nil
+	return URL
 }

pkg/registry/auth/auth_test.go

@@ -4,13 +4,15 @@ import (
 	"fmt"
 	"net/url"
 	"os"
+	"strings"
 	"testing"
 	"time"
 
 	"github.com/containrrr/watchtower/internal/actions/mocks"
 	"github.com/containrrr/watchtower/pkg/registry/auth"
 
 	wtTypes "github.com/containrrr/watchtower/pkg/types"
+	ref "github.com/docker/distribution/reference"
 	. "github.com/onsi/ginkgo"
 	. "github.com/onsi/gomega"
 )
@@ -52,7 +54,7 @@ var _ = Describe("the auth module", func() {
 		mockCreated,
 		mockDigest)
 
-	When("getting an auth url", func() {
+	Describe("GetToken", func() {
 		It("should parse the token from the response",
 			SkipIfCredentialsEmpty(GHCRCredentials, func() {
 				creds := fmt.Sprintf("%s:%s", GHCRCredentials.Username, GHCRCredentials.Password)
@@ -61,73 +63,100 @@ var _ = Describe("the auth module", func() {
 				Expect(token).NotTo(Equal(""))
 			}),
 		)
+	})
 
+	Describe("GetAuthURL", func() {
 		It("should create a valid auth url object based on the challenge header supplied", func() {
-			input := `bearer realm="https://ghcr.io/token",service="ghcr.io",scope="repository:user/image:pull"`
+			challenge := `bearer realm="https://ghcr.io/token",service="ghcr.io",scope="repository:user/image:pull"`
+			imageRef, err := ref.ParseNormalizedNamed("containrrr/watchtower")
+			Expect(err).NotTo(HaveOccurred())
 			expected := &url.URL{
 				Host:     "ghcr.io",
 				Scheme:   "https",
 				Path:     "/token",
 				RawQuery: "scope=repository%3Acontainrrr%2Fwatchtower%3Apull&service=ghcr.io",
 			}
-			res, err := auth.GetAuthURL(input, "containrrr/watchtower")
+
+			URL, err := auth.GetAuthURL(challenge, imageRef)
 			Expect(err).NotTo(HaveOccurred())
-			Expect(res).To(Equal(expected))
+			Expect(URL).To(Equal(expected))
 		})
-		It("should create a valid auth url object based on the challenge header supplied", func() {
-			input := `bearer realm="https://ghcr.io/token"`
-			res, err := auth.GetAuthURL(input, "containrrr/watchtower")
-			Expect(err).To(HaveOccurred())
-			Expect(res).To(BeNil())
+
+		When("given an invalid challenge header", func() {
+			It("should return an error", func() {
+				challenge := `bearer realm="https://ghcr.io/token"`
+				imageRef, err := ref.ParseNormalizedNamed("containrrr/watchtower")
+				Expect(err).NotTo(HaveOccurred())
+				URL, err := auth.GetAuthURL(challenge, imageRef)
+				Expect(err).To(HaveOccurred())
+				Expect(URL).To(BeNil())
+			})
+		})
+
+		When("deriving the auth scope from an image name", func() {
+			It("should prepend official dockerhub images with \"library/\"", func() {
+				Expect(getScopeFromImageAuthURL("registry")).To(Equal("library/registry"))
+				Expect(getScopeFromImageAuthURL("docker.io/registry")).To(Equal("library/registry"))
+				Expect(getScopeFromImageAuthURL("index.docker.io/registry")).To(Equal("library/registry"))
+			})
+			It("should not include vanity hosts\"", func() {
+				Expect(getScopeFromImageAuthURL("docker.io/containrrr/watchtower")).To(Equal("containrrr/watchtower"))
+				Expect(getScopeFromImageAuthURL("index.docker.io/containrrr/watchtower")).To(Equal("containrrr/watchtower"))
+			})
+			It("should not destroy three segment image names\"", func() {
+				Expect(getScopeFromImageAuthURL("piksel/containrrr/watchtower")).To(Equal("piksel/containrrr/watchtower"))
+				Expect(getScopeFromImageAuthURL("ghcr.io/piksel/containrrr/watchtower")).To(Equal("piksel/containrrr/watchtower"))
+			})
+			It("should not prepend library/ to image names if they're not on dockerhub", func() {
+				Expect(getScopeFromImageAuthURL("ghcr.io/watchtower")).To(Equal("watchtower"))
+				Expect(getScopeFromImageAuthURL("ghcr.io/containrrr/watchtower")).To(Equal("containrrr/watchtower"))
+			})
 		})
 		It("should not crash when an empty field is recieved", func() {
 			input := `bearer realm="https://ghcr.io/token",service="ghcr.io",scope="repository:user/image:pull",`
-			res, err := auth.GetAuthURL(input, "containrrr/watchtower")
+			imageRef, err := ref.ParseNormalizedNamed("containrrr/watchtower")
+			Expect(err).NotTo(HaveOccurred())
+			res, err := auth.GetAuthURL(input, imageRef)
 			Expect(err).NotTo(HaveOccurred())
 			Expect(res).NotTo(BeNil())
 		})
 		It("should not crash when a field without a value is recieved", func() {
 			input := `bearer realm="https://ghcr.io/token",service="ghcr.io",scope="repository:user/image:pull",valuelesskey`
-			res, err := auth.GetAuthURL(input, "containrrr/watchtower")
+			imageRef, err := ref.ParseNormalizedNamed("containrrr/watchtower")
+			Expect(err).NotTo(HaveOccurred())
+			res, err := auth.GetAuthURL(input, imageRef)
 			Expect(err).NotTo(HaveOccurred())
 			Expect(res).NotTo(BeNil())
 		})
 	})
-	When("getting a challenge url", func() {
+
+	Describe("GetChallengeURL", func() {
 		It("should create a valid challenge url object based on the image ref supplied", func() {
 			expected := url.URL{Host: "ghcr.io", Scheme: "https", Path: "/v2/"}
-			Expect(auth.GetChallengeURL("ghcr.io/containrrr/watchtower:latest")).To(Equal(expected))
+			imageRef, _ := ref.ParseNormalizedNamed("ghcr.io/containrrr/watchtower:latest")
+			Expect(auth.GetChallengeURL(imageRef)).To(Equal(expected))
 		})
-		It("should assume dockerhub if the image ref is not fully qualified", func() {
+		It("should assume Docker Hub for image refs with no explicit registry", func() {
 			expected := url.URL{Host: "index.docker.io", Scheme: "https", Path: "/v2/"}
-			Expect(auth.GetChallengeURL("containrrr/watchtower:latest")).To(Equal(expected))
+			imageRef, _ := ref.ParseNormalizedNamed("containrrr/watchtower:latest")
+			Expect(auth.GetChallengeURL(imageRef)).To(Equal(expected))
 		})
-		It("should convert legacy dockerhub hostnames to index.docker.io", func() {
+		It("should use index.docker.io if the image ref specifies docker.io", func() {
 			expected := url.URL{Host: "index.docker.io", Scheme: "https", Path: "/v2/"}
-			Expect(auth.GetChallengeURL("docker.io/containrrr/watchtower:latest")).To(Equal(expected))
-			Expect(auth.GetChallengeURL("registry-1.docker.io/containrrr/watchtower:latest")).To(Equal(expected))
+			imageRef, _ := ref.ParseNormalizedNamed("docker.io/containrrr/watchtower:latest")
+			Expect(auth.GetChallengeURL(imageRef)).To(Equal(expected))
 		})
 	})
-	When("getting the auth scope from an image name", func() {
-		It("should prepend official dockerhub images with \"library/\"", func() {
-			Expect(auth.GetScopeFromImageName("docker.io/registry", "index.docker.io")).To(Equal("library/registry"))
-			Expect(auth.GetScopeFromImageName("docker.io/registry", "docker.io")).To(Equal("library/registry"))
+})
 
-			Expect(auth.GetScopeFromImageName("registry", "index.docker.io")).To(Equal("library/registry"))
-			Expect(auth.GetScopeFromImageName("watchtower", "registry-1.docker.io")).To(Equal("library/watchtower"))
+var scopeImageRegexp = MatchRegexp("^repository:[a-z0-9]+(/[a-z0-9]+)*:pull$")
 
-		})
-		It("should not include vanity hosts\"", func() {
-			Expect(auth.GetScopeFromImageName("docker.io/containrrr/watchtower", "index.docker.io")).To(Equal("containrrr/watchtower"))
-			Expect(auth.GetScopeFromImageName("index.docker.io/containrrr/watchtower", "index.docker.io")).To(Equal("containrrr/watchtower"))
-		})
-		It("should not destroy three segment image names\"", func() {
-			Expect(auth.GetScopeFromImageName("piksel/containrrr/watchtower", "index.docker.io")).To(Equal("containrrr/watchtower"))
-			Expect(auth.GetScopeFromImageName("piksel/containrrr/watchtower", "ghcr.io")).To(Equal("piksel/containrrr/watchtower"))
-		})
-		It("should not add \"library/\" for one segment image names if they're not on dockerhub", func() {
-			Expect(auth.GetScopeFromImageName("ghcr.io/watchtower", "ghcr.io")).To(Equal("watchtower"))
-			Expect(auth.GetScopeFromImageName("watchtower", "ghcr.io")).To(Equal("watchtower"))
-		})
-	})
-})
+func getScopeFromImageAuthURL(imageName string) string {
+	normalizedRef, _ := ref.ParseNormalizedNamed(imageName)
+	challenge := `bearer realm="https://dummy.host/token",service="dummy.host",scope="repository:user/image:pull"`
+	URL, _ := auth.GetAuthURL(challenge, normalizedRef)
+
+	scope := URL.Query().Get("scope")
+	Expect(scopeImageRegexp.Match(scope)).To(BeTrue())
+	return strings.Replace(scope[11:], ":pull", "", 1)
+}