1 // Copyright 2015 go-dockerclient authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style
3 // license that can be found in the LICENSE file.
20 // APIImages represent an image returned in the ListImages call.
21 type APIImages struct {
22 ID string `json:"Id" yaml:"Id"`
23 RepoTags []string `json:"RepoTags,omitempty" yaml:"RepoTags,omitempty"`
24 Created int64 `json:"Created,omitempty" yaml:"Created,omitempty"`
25 Size int64 `json:"Size,omitempty" yaml:"Size,omitempty"`
26 VirtualSize int64 `json:"VirtualSize,omitempty" yaml:"VirtualSize,omitempty"`
27 ParentID string `json:"ParentId,omitempty" yaml:"ParentId,omitempty"`
28 RepoDigests []string `json:"RepoDigests,omitempty" yaml:"RepoDigests,omitempty"`
29 Labels map[string]string `json:"Labels,omitempty" yaml:"Labels,omitempty"`
32 // RootFS represents the underlying layers used by an image
34 Type string `json:"Type,omitempty" yaml:"Type,omitempty"`
35 Layers []string `json:"Layers,omitempty" yaml:"Layers,omitempty"`
38 // Image is the type representing a docker image and its various properties
40 ID string `json:"Id" yaml:"Id"`
41 RepoTags []string `json:"RepoTags,omitempty" yaml:"RepoTags,omitempty"`
42 Parent string `json:"Parent,omitempty" yaml:"Parent,omitempty"`
43 Comment string `json:"Comment,omitempty" yaml:"Comment,omitempty"`
44 Created time.Time `json:"Created,omitempty" yaml:"Created,omitempty"`
45 Container string `json:"Container,omitempty" yaml:"Container,omitempty"`
46 ContainerConfig Config `json:"ContainerConfig,omitempty" yaml:"ContainerConfig,omitempty"`
47 DockerVersion string `json:"DockerVersion,omitempty" yaml:"DockerVersion,omitempty"`
48 Author string `json:"Author,omitempty" yaml:"Author,omitempty"`
49 Config *Config `json:"Config,omitempty" yaml:"Config,omitempty"`
50 Architecture string `json:"Architecture,omitempty" yaml:"Architecture,omitempty"`
51 Size int64 `json:"Size,omitempty" yaml:"Size,omitempty"`
52 VirtualSize int64 `json:"VirtualSize,omitempty" yaml:"VirtualSize,omitempty"`
53 RepoDigests []string `json:"RepoDigests,omitempty" yaml:"RepoDigests,omitempty"`
54 RootFS *RootFS `json:"RootFS,omitempty" yaml:"RootFS,omitempty"`
57 // ImagePre012 serves the same purpose as the Image type except that it is for
58 // earlier versions of the Docker API (pre-012 to be specific)
59 type ImagePre012 struct {
61 Parent string `json:"parent,omitempty"`
62 Comment string `json:"comment,omitempty"`
63 Created time.Time `json:"created"`
64 Container string `json:"container,omitempty"`
65 ContainerConfig Config `json:"container_config,omitempty"`
66 DockerVersion string `json:"docker_version,omitempty"`
67 Author string `json:"author,omitempty"`
68 Config *Config `json:"config,omitempty"`
69 Architecture string `json:"architecture,omitempty"`
70 Size int64 `json:"size,omitempty"`
74 // ErrNoSuchImage is the error returned when the image does not exist.
75 ErrNoSuchImage = errors.New("no such image")
77 // ErrMissingRepo is the error returned when the remote repository is
79 ErrMissingRepo = errors.New("missing remote repository e.g. 'github.com/user/repo'")
81 // ErrMissingOutputStream is the error returned when no output stream
82 // is provided to some calls, like BuildImage.
83 ErrMissingOutputStream = errors.New("missing output stream")
85 // ErrMultipleContexts is the error returned when both a ContextDir and
86 // InputStream are provided in BuildImageOptions
87 ErrMultipleContexts = errors.New("image build may not be provided BOTH context dir and input stream")
89 // ErrMustSpecifyNames is the error rreturned when the Names field on
90 // ExportImagesOptions is nil or empty
91 ErrMustSpecifyNames = errors.New("must specify at least one name to export")
94 // ListImagesOptions specify parameters to the ListImages function.
96 // See https://goo.gl/xBe1u3 for more details.
97 type ListImagesOptions struct {
99 Filters map[string][]string
104 // ListImages returns the list of available images in the server.
106 // See https://goo.gl/xBe1u3 for more details.
107 func (c *Client) ListImages(opts ListImagesOptions) ([]APIImages, error) {
108 path := "/images/json?" + queryString(opts)
109 resp, err := c.do("GET", path, doOptions{})
113 defer resp.Body.Close()
114 var images []APIImages
115 if err := json.NewDecoder(resp.Body).Decode(&images); err != nil {
121 // ImageHistory represent a layer in an image's history returned by the
122 // ImageHistory call.
123 type ImageHistory struct {
124 ID string `json:"Id" yaml:"Id"`
125 Tags []string `json:"Tags,omitempty" yaml:"Tags,omitempty"`
126 Created int64 `json:"Created,omitempty" yaml:"Created,omitempty"`
127 CreatedBy string `json:"CreatedBy,omitempty" yaml:"CreatedBy,omitempty"`
128 Size int64 `json:"Size,omitempty" yaml:"Size,omitempty"`
131 // ImageHistory returns the history of the image by its name or ID.
133 // See https://goo.gl/8bnTId for more details.
134 func (c *Client) ImageHistory(name string) ([]ImageHistory, error) {
135 resp, err := c.do("GET", "/images/"+name+"/history", doOptions{})
137 if e, ok := err.(*Error); ok && e.Status == http.StatusNotFound {
138 return nil, ErrNoSuchImage
142 defer resp.Body.Close()
143 var history []ImageHistory
144 if err := json.NewDecoder(resp.Body).Decode(&history); err != nil {
150 // RemoveImage removes an image by its name or ID.
152 // See https://goo.gl/V3ZWnK for more details.
153 func (c *Client) RemoveImage(name string) error {
154 resp, err := c.do("DELETE", "/images/"+name, doOptions{})
156 if e, ok := err.(*Error); ok && e.Status == http.StatusNotFound {
157 return ErrNoSuchImage
165 // RemoveImageOptions present the set of options available for removing an image
168 // See https://goo.gl/V3ZWnK for more details.
169 type RemoveImageOptions struct {
170 Force bool `qs:"force"`
171 NoPrune bool `qs:"noprune"`
174 // RemoveImageExtended removes an image by its name or ID.
175 // Extra params can be passed, see RemoveImageOptions
177 // See https://goo.gl/V3ZWnK for more details.
178 func (c *Client) RemoveImageExtended(name string, opts RemoveImageOptions) error {
179 uri := fmt.Sprintf("/images/%s?%s", name, queryString(&opts))
180 resp, err := c.do("DELETE", uri, doOptions{})
182 if e, ok := err.(*Error); ok && e.Status == http.StatusNotFound {
183 return ErrNoSuchImage
191 // InspectImage returns an image by its name or ID.
193 // See https://goo.gl/jHPcg6 for more details.
194 func (c *Client) InspectImage(name string) (*Image, error) {
195 resp, err := c.do("GET", "/images/"+name+"/json", doOptions{})
197 if e, ok := err.(*Error); ok && e.Status == http.StatusNotFound {
198 return nil, ErrNoSuchImage
202 defer resp.Body.Close()
206 // if the caller elected to skip checking the server's version, assume it's the latest
207 if c.SkipServerVersionCheck || c.expectedAPIVersion.GreaterThanOrEqualTo(apiVersion112) {
208 if err := json.NewDecoder(resp.Body).Decode(&image); err != nil {
212 var imagePre012 ImagePre012
213 if err := json.NewDecoder(resp.Body).Decode(&imagePre012); err != nil {
217 image.ID = imagePre012.ID
218 image.Parent = imagePre012.Parent
219 image.Comment = imagePre012.Comment
220 image.Created = imagePre012.Created
221 image.Container = imagePre012.Container
222 image.ContainerConfig = imagePre012.ContainerConfig
223 image.DockerVersion = imagePre012.DockerVersion
224 image.Author = imagePre012.Author
225 image.Config = imagePre012.Config
226 image.Architecture = imagePre012.Architecture
227 image.Size = imagePre012.Size
233 // PushImageOptions represents options to use in the PushImage method.
235 // See https://goo.gl/zPtZaT for more details.
236 type PushImageOptions struct {
243 // Registry server to push the image
246 OutputStream io.Writer `qs:"-"`
247 RawJSONStream bool `qs:"-"`
248 InactivityTimeout time.Duration `qs:"-"`
251 // PushImage pushes an image to a remote registry, logging progress to w.
253 // An empty instance of AuthConfiguration may be used for unauthenticated
256 // See https://goo.gl/zPtZaT for more details.
257 func (c *Client) PushImage(opts PushImageOptions, auth AuthConfiguration) error {
259 return ErrNoSuchImage
261 headers, err := headersWithAuth(auth)
267 path := "/images/" + name + "/push?" + queryString(&opts)
268 return c.stream("POST", path, streamOptions{
269 setRawTerminal: true,
270 rawJSONStream: opts.RawJSONStream,
272 stdout: opts.OutputStream,
273 inactivityTimeout: opts.InactivityTimeout,
277 // PullImageOptions present the set of options available for pulling an image
280 // See https://goo.gl/iJkZjD for more details.
281 type PullImageOptions struct {
282 Repository string `qs:"fromImage"`
286 OutputStream io.Writer `qs:"-"`
287 RawJSONStream bool `qs:"-"`
288 InactivityTimeout time.Duration `qs:"-"`
291 // PullImage pulls an image from a remote registry, logging progress to
292 // opts.OutputStream.
294 // See https://goo.gl/iJkZjD for more details.
295 func (c *Client) PullImage(opts PullImageOptions, auth AuthConfiguration) error {
296 if opts.Repository == "" {
297 return ErrNoSuchImage
300 headers, err := headersWithAuth(auth)
304 return c.createImage(queryString(&opts), headers, nil, opts.OutputStream, opts.RawJSONStream, opts.InactivityTimeout)
307 func (c *Client) createImage(qs string, headers map[string]string, in io.Reader, w io.Writer, rawJSONStream bool, timeout time.Duration) error {
308 path := "/images/create?" + qs
309 return c.stream("POST", path, streamOptions{
310 setRawTerminal: true,
314 rawJSONStream: rawJSONStream,
315 inactivityTimeout: timeout,
319 // LoadImageOptions represents the options for LoadImage Docker API Call
321 // See https://goo.gl/JyClMX for more details.
322 type LoadImageOptions struct {
323 InputStream io.Reader
326 // LoadImage imports a tarball docker image
328 // See https://goo.gl/JyClMX for more details.
329 func (c *Client) LoadImage(opts LoadImageOptions) error {
330 return c.stream("POST", "/images/load", streamOptions{
331 setRawTerminal: true,
332 in: opts.InputStream,
336 // ExportImageOptions represent the options for ExportImage Docker API call.
338 // See https://goo.gl/le7vK8 for more details.
339 type ExportImageOptions struct {
341 OutputStream io.Writer
342 InactivityTimeout time.Duration `qs:"-"`
345 // ExportImage exports an image (as a tar file) into the stream.
347 // See https://goo.gl/le7vK8 for more details.
348 func (c *Client) ExportImage(opts ExportImageOptions) error {
349 return c.stream("GET", fmt.Sprintf("/images/%s/get", opts.Name), streamOptions{
350 setRawTerminal: true,
351 stdout: opts.OutputStream,
352 inactivityTimeout: opts.InactivityTimeout,
356 // ExportImagesOptions represent the options for ExportImages Docker API call
358 // See https://goo.gl/huC7HA for more details.
359 type ExportImagesOptions struct {
361 OutputStream io.Writer `qs:"-"`
362 InactivityTimeout time.Duration `qs:"-"`
365 // ExportImages exports one or more images (as a tar file) into the stream
367 // See https://goo.gl/huC7HA for more details.
368 func (c *Client) ExportImages(opts ExportImagesOptions) error {
369 if opts.Names == nil || len(opts.Names) == 0 {
370 return ErrMustSpecifyNames
372 return c.stream("GET", "/images/get?"+queryString(&opts), streamOptions{
373 setRawTerminal: true,
374 stdout: opts.OutputStream,
375 inactivityTimeout: opts.InactivityTimeout,
379 // ImportImageOptions present the set of informations available for importing
380 // an image from a source file or the stdin.
382 // See https://goo.gl/iJkZjD for more details.
383 type ImportImageOptions struct {
384 Repository string `qs:"repo"`
385 Source string `qs:"fromSrc"`
386 Tag string `qs:"tag"`
388 InputStream io.Reader `qs:"-"`
389 OutputStream io.Writer `qs:"-"`
390 RawJSONStream bool `qs:"-"`
391 InactivityTimeout time.Duration `qs:"-"`
394 // ImportImage imports an image from a url, a file or stdin
396 // See https://goo.gl/iJkZjD for more details.
397 func (c *Client) ImportImage(opts ImportImageOptions) error {
398 if opts.Repository == "" {
399 return ErrNoSuchImage
401 if opts.Source != "-" {
402 opts.InputStream = nil
404 if opts.Source != "-" && !isURL(opts.Source) {
405 f, err := os.Open(opts.Source)
412 return c.createImage(queryString(&opts), nil, opts.InputStream, opts.OutputStream, opts.RawJSONStream, opts.InactivityTimeout)
415 // BuildImageOptions present the set of informations available for building an
416 // image from a tarfile with a Dockerfile in it.
418 // For more details about the Docker building process, see
419 // http://goo.gl/tlPXPu.
420 type BuildImageOptions struct {
422 Dockerfile string `qs:"dockerfile"`
423 NoCache bool `qs:"nocache"`
424 SuppressOutput bool `qs:"q"`
425 Pull bool `qs:"pull"`
426 RmTmpContainer bool `qs:"rm"`
427 ForceRmTmpContainer bool `qs:"forcerm"`
428 Memory int64 `qs:"memory"`
429 Memswap int64 `qs:"memswap"`
430 CPUShares int64 `qs:"cpushares"`
431 CPUQuota int64 `qs:"cpuquota"`
432 CPUPeriod int64 `qs:"cpuperiod"`
433 CPUSetCPUs string `qs:"cpusetcpus"`
434 InputStream io.Reader `qs:"-"`
435 OutputStream io.Writer `qs:"-"`
436 RawJSONStream bool `qs:"-"`
437 Remote string `qs:"remote"`
438 Auth AuthConfiguration `qs:"-"` // for older docker X-Registry-Auth header
439 AuthConfigs AuthConfigurations `qs:"-"` // for newer docker X-Registry-Config header
440 ContextDir string `qs:"-"`
441 Ulimits []ULimit `qs:"-"`
442 BuildArgs []BuildArg `qs:"-"`
443 InactivityTimeout time.Duration `qs:"-"`
446 // BuildArg represents arguments that can be passed to the image when building
447 // it from a Dockerfile.
449 // For more details about the Docker building process, see
450 // http://goo.gl/tlPXPu.
451 type BuildArg struct {
452 Name string `json:"Name,omitempty" yaml:"Name,omitempty"`
453 Value string `json:"Value,omitempty" yaml:"Value,omitempty"`
456 // BuildImage builds an image from a tarball's url or a Dockerfile in the input
459 // See https://goo.gl/xySxCe for more details.
460 func (c *Client) BuildImage(opts BuildImageOptions) error {
461 if opts.OutputStream == nil {
462 return ErrMissingOutputStream
464 headers, err := headersWithAuth(opts.Auth, c.versionedAuthConfigs(opts.AuthConfigs))
469 if opts.Remote != "" && opts.Name == "" {
470 opts.Name = opts.Remote
472 if opts.InputStream != nil || opts.ContextDir != "" {
473 headers["Content-Type"] = "application/tar"
474 } else if opts.Remote == "" {
475 return ErrMissingRepo
477 if opts.ContextDir != "" {
478 if opts.InputStream != nil {
479 return ErrMultipleContexts
482 if opts.InputStream, err = createTarStream(opts.ContextDir, opts.Dockerfile); err != nil {
487 qs := queryString(&opts)
488 if len(opts.Ulimits) > 0 {
489 if b, err := json.Marshal(opts.Ulimits); err == nil {
490 item := url.Values(map[string][]string{})
491 item.Add("ulimits", string(b))
492 qs = fmt.Sprintf("%s&%s", qs, item.Encode())
496 if len(opts.BuildArgs) > 0 {
497 v := make(map[string]string)
498 for _, arg := range opts.BuildArgs {
499 v[arg.Name] = arg.Value
501 if b, err := json.Marshal(v); err == nil {
502 item := url.Values(map[string][]string{})
503 item.Add("buildargs", string(b))
504 qs = fmt.Sprintf("%s&%s", qs, item.Encode())
508 return c.stream("POST", fmt.Sprintf("/build?%s", qs), streamOptions{
509 setRawTerminal: true,
510 rawJSONStream: opts.RawJSONStream,
512 in: opts.InputStream,
513 stdout: opts.OutputStream,
514 inactivityTimeout: opts.InactivityTimeout,
518 func (c *Client) versionedAuthConfigs(authConfigs AuthConfigurations) interface{} {
519 if c.serverAPIVersion == nil {
522 if c.serverAPIVersion != nil && c.serverAPIVersion.GreaterThanOrEqualTo(apiVersion119) {
523 return AuthConfigurations119(authConfigs.Configs)
528 // TagImageOptions present the set of options to tag an image.
530 // See https://goo.gl/98ZzkU for more details.
531 type TagImageOptions struct {
537 // TagImage adds a tag to the image identified by the given name.
539 // See https://goo.gl/98ZzkU for more details.
540 func (c *Client) TagImage(name string, opts TagImageOptions) error {
542 return ErrNoSuchImage
544 resp, err := c.do("POST", fmt.Sprintf("/images/"+name+"/tag?%s",
545 queryString(&opts)), doOptions{})
551 defer resp.Body.Close()
553 if resp.StatusCode == http.StatusNotFound {
554 return ErrNoSuchImage
560 func isURL(u string) bool {
561 p, err := url.Parse(u)
565 return p.Scheme == "http" || p.Scheme == "https"
568 func headersWithAuth(auths ...interface{}) (map[string]string, error) {
569 var headers = make(map[string]string)
571 for _, auth := range auths {
573 case AuthConfiguration:
575 if err := json.NewEncoder(&buf).Encode(auth); err != nil {
578 headers["X-Registry-Auth"] = base64.URLEncoding.EncodeToString(buf.Bytes())
579 case AuthConfigurations, AuthConfigurations119:
581 if err := json.NewEncoder(&buf).Encode(auth); err != nil {
584 headers["X-Registry-Config"] = base64.URLEncoding.EncodeToString(buf.Bytes())
591 // APIImageSearch reflect the result of a search on the Docker Hub.
593 // See https://goo.gl/AYjyrF for more details.
594 type APIImageSearch struct {
595 Description string `json:"description,omitempty" yaml:"description,omitempty"`
596 IsOfficial bool `json:"is_official,omitempty" yaml:"is_official,omitempty"`
597 IsAutomated bool `json:"is_automated,omitempty" yaml:"is_automated,omitempty"`
598 Name string `json:"name,omitempty" yaml:"name,omitempty"`
599 StarCount int `json:"star_count,omitempty" yaml:"star_count,omitempty"`
602 // SearchImages search the docker hub with a specific given term.
604 // See https://goo.gl/AYjyrF for more details.
605 func (c *Client) SearchImages(term string) ([]APIImageSearch, error) {
606 resp, err := c.do("GET", "/images/search?term="+term, doOptions{})
610 defer resp.Body.Close()
611 var searchResult []APIImageSearch
612 if err := json.NewDecoder(resp.Body).Decode(&searchResult); err != nil {
615 return searchResult, nil
618 // SearchImagesEx search the docker hub with a specific given term and authentication.
620 // See https://goo.gl/AYjyrF for more details.
621 func (c *Client) SearchImagesEx(term string, auth AuthConfiguration) ([]APIImageSearch, error) {
622 headers, err := headersWithAuth(auth)
627 resp, err := c.do("GET", "/images/search?term="+term, doOptions{
634 defer resp.Body.Close()
636 var searchResult []APIImageSearch
637 if err := json.NewDecoder(resp.Body).Decode(&searchResult); err != nil {
641 return searchResult, nil