1package distribution // import "github.com/docker/docker/distribution"
2
3import (
4	"context"
5	"fmt"
6
7	"github.com/docker/distribution/reference"
8	"github.com/docker/docker/api"
9	"github.com/docker/docker/distribution/metadata"
10	"github.com/docker/docker/pkg/progress"
11	refstore "github.com/docker/docker/reference"
12	"github.com/docker/docker/registry"
13	"github.com/opencontainers/go-digest"
14	specs "github.com/opencontainers/image-spec/specs-go/v1"
15	"github.com/pkg/errors"
16	"github.com/sirupsen/logrus"
17)
18
19// Puller is an interface that abstracts pulling for different API versions.
20type Puller interface {
21	// Pull tries to pull the image referenced by `tag`
22	// Pull returns an error if any, as well as a boolean that determines whether to retry Pull on the next configured endpoint.
23	//
24	Pull(ctx context.Context, ref reference.Named, platform *specs.Platform) error
25}
26
27// newPuller returns a Puller interface that will pull from either a v1 or v2
28// registry. The endpoint argument contains a Version field that determines
29// whether a v1 or v2 puller will be created. The other parameters are passed
30// through to the underlying puller implementation for use during the actual
31// pull operation.
32func newPuller(endpoint registry.APIEndpoint, repoInfo *registry.RepositoryInfo, imagePullConfig *ImagePullConfig) (Puller, error) {
33	switch endpoint.Version {
34	case registry.APIVersion2:
35		return &v2Puller{
36			V2MetadataService: metadata.NewV2MetadataService(imagePullConfig.MetadataStore),
37			endpoint:          endpoint,
38			config:            imagePullConfig,
39			repoInfo:          repoInfo,
40		}, nil
41	case registry.APIVersion1:
42		return &v1Puller{
43			v1IDService: metadata.NewV1IDService(imagePullConfig.MetadataStore),
44			endpoint:    endpoint,
45			config:      imagePullConfig,
46			repoInfo:    repoInfo,
47		}, nil
48	}
49	return nil, fmt.Errorf("unknown version %d for registry %s", endpoint.Version, endpoint.URL)
50}
51
52// Pull initiates a pull operation. image is the repository name to pull, and
53// tag may be either empty, or indicate a specific tag to pull.
54func Pull(ctx context.Context, ref reference.Named, imagePullConfig *ImagePullConfig) error {
55	// Resolve the Repository name from fqn to RepositoryInfo
56	repoInfo, err := imagePullConfig.RegistryService.ResolveRepository(ref)
57	if err != nil {
58		return err
59	}
60
61	// makes sure name is not `scratch`
62	if err := ValidateRepoName(repoInfo.Name); err != nil {
63		return err
64	}
65
66	endpoints, err := imagePullConfig.RegistryService.LookupPullEndpoints(reference.Domain(repoInfo.Name))
67	if err != nil {
68		return err
69	}
70
71	var (
72		lastErr error
73
74		// discardNoSupportErrors is used to track whether an endpoint encountered an error of type registry.ErrNoSupport
75		// By default it is false, which means that if an ErrNoSupport error is encountered, it will be saved in lastErr.
76		// As soon as another kind of error is encountered, discardNoSupportErrors is set to true, avoiding the saving of
77		// any subsequent ErrNoSupport errors in lastErr.
78		// It's needed for pull-by-digest on v1 endpoints: if there are only v1 endpoints configured, the error should be
79		// returned and displayed, but if there was a v2 endpoint which supports pull-by-digest, then the last relevant
80		// error is the ones from v2 endpoints not v1.
81		discardNoSupportErrors bool
82
83		// confirmedV2 is set to true if a pull attempt managed to
84		// confirm that it was talking to a v2 registry. This will
85		// prevent fallback to the v1 protocol.
86		confirmedV2 bool
87
88		// confirmedTLSRegistries is a map indicating which registries
89		// are known to be using TLS. There should never be a plaintext
90		// retry for any of these.
91		confirmedTLSRegistries = make(map[string]struct{})
92	)
93	for _, endpoint := range endpoints {
94		if imagePullConfig.RequireSchema2 && endpoint.Version == registry.APIVersion1 {
95			continue
96		}
97
98		if confirmedV2 && endpoint.Version == registry.APIVersion1 {
99			logrus.Debugf("Skipping v1 endpoint %s because v2 registry was detected", endpoint.URL)
100			continue
101		}
102
103		if endpoint.URL.Scheme != "https" {
104			if _, confirmedTLS := confirmedTLSRegistries[endpoint.URL.Host]; confirmedTLS {
105				logrus.Debugf("Skipping non-TLS endpoint %s for host/port that appears to use TLS", endpoint.URL)
106				continue
107			}
108		}
109
110		logrus.Debugf("Trying to pull %s from %s %s", reference.FamiliarName(repoInfo.Name), endpoint.URL, endpoint.Version)
111
112		puller, err := newPuller(endpoint, repoInfo, imagePullConfig)
113		if err != nil {
114			lastErr = err
115			continue
116		}
117
118		if err := puller.Pull(ctx, ref, imagePullConfig.Platform); err != nil {
119			// Was this pull cancelled? If so, don't try to fall
120			// back.
121			fallback := false
122			select {
123			case <-ctx.Done():
124			default:
125				if fallbackErr, ok := err.(fallbackError); ok {
126					fallback = true
127					confirmedV2 = confirmedV2 || fallbackErr.confirmedV2
128					if fallbackErr.transportOK && endpoint.URL.Scheme == "https" {
129						confirmedTLSRegistries[endpoint.URL.Host] = struct{}{}
130					}
131					err = fallbackErr.err
132				}
133			}
134			if fallback {
135				if _, ok := err.(ErrNoSupport); !ok {
136					// Because we found an error that's not ErrNoSupport, discard all subsequent ErrNoSupport errors.
137					discardNoSupportErrors = true
138					// append subsequent errors
139					lastErr = err
140				} else if !discardNoSupportErrors {
141					// Save the ErrNoSupport error, because it's either the first error or all encountered errors
142					// were also ErrNoSupport errors.
143					// append subsequent errors
144					lastErr = err
145				}
146				logrus.Infof("Attempting next endpoint for pull after error: %v", err)
147				continue
148			}
149			logrus.Errorf("Not continuing with pull after error: %v", err)
150			return TranslatePullError(err, ref)
151		}
152
153		imagePullConfig.ImageEventLogger(reference.FamiliarString(ref), reference.FamiliarName(repoInfo.Name), "pull")
154		return nil
155	}
156
157	if lastErr == nil {
158		lastErr = fmt.Errorf("no endpoints found for %s", reference.FamiliarString(ref))
159	}
160
161	return TranslatePullError(lastErr, ref)
162}
163
164// writeStatus writes a status message to out. If layersDownloaded is true, the
165// status message indicates that a newer image was downloaded. Otherwise, it
166// indicates that the image is up to date. requestedTag is the tag the message
167// will refer to.
168func writeStatus(requestedTag string, out progress.Output, layersDownloaded bool) {
169	if layersDownloaded {
170		progress.Message(out, "", "Status: Downloaded newer image for "+requestedTag)
171	} else {
172		progress.Message(out, "", "Status: Image is up to date for "+requestedTag)
173	}
174}
175
176// ValidateRepoName validates the name of a repository.
177func ValidateRepoName(name reference.Named) error {
178	if reference.FamiliarName(name) == api.NoBaseImageSpecifier {
179		return errors.WithStack(reservedNameError(api.NoBaseImageSpecifier))
180	}
181	return nil
182}
183
184func addDigestReference(store refstore.Store, ref reference.Named, dgst digest.Digest, id digest.Digest) error {
185	dgstRef, err := reference.WithDigest(reference.TrimNamed(ref), dgst)
186	if err != nil {
187		return err
188	}
189
190	if oldTagID, err := store.Get(dgstRef); err == nil {
191		if oldTagID != id {
192			// Updating digests not supported by reference store
193			logrus.Errorf("Image ID for digest %s changed from %s to %s, cannot update", dgst.String(), oldTagID, id)
194		}
195		return nil
196	} else if err != refstore.ErrDoesNotExist {
197		return err
198	}
199
200	return store.AddDigest(dgstRef, id, true)
201}
202