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