{"action":"created","issue":{"url":"https://api.github.com/repos/docker/docker/issues/11109","labels_url":"https://api.github.com/repos/docker/docker/issues/11109/labels{/name}","comments_url":"https://api.github.com/repos/docker/docker/issues/11109/comments","events_url":"https://api.github.com/repos/docker/docker/issues/11109/events","html_url":"https://github.com/docker/docker/pull/11109","id":59504969,"number":11109,"title":"Add support for referring to images by digest","user":{"login":"ncdc","id":354,"avatar_url":"https://avatars.githubusercontent.com/u/354?v=3","gravatar_id":"","url":"https://api.github.com/users/ncdc","html_url":"https://github.com/ncdc","followers_url":"https://api.github.com/users/ncdc/followers","following_url":"https://api.github.com/users/ncdc/following{/other_user}","gists_url":"https://api.github.com/users/ncdc/gists{/gist_id}","starred_url":"https://api.github.com/users/ncdc/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ncdc/subscriptions","organizations_url":"https://api.github.com/users/ncdc/orgs","repos_url":"https://api.github.com/users/ncdc/repos","events_url":"https://api.github.com/users/ncdc/events{/privacy}","received_events_url":"https://api.github.com/users/ncdc/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/docker/docker/labels/3-docs-review","name":"3-docs-review","color":"c7def8"},{"url":"https://api.github.com/repos/docker/docker/labels/Distribution","name":"Distribution","color":"e11d21"}],"state":"open","locked":false,"assignee":{"login":"stevvooe","id":120601,"avatar_url":"https://avatars.githubusercontent.com/u/120601?v=3","gravatar_id":"","url":"https://api.github.com/users/stevvooe","html_url":"https://github.com/stevvooe","followers_url":"https://api.github.com/users/stevvooe/followers","following_url":"https://api.github.com/users/stevvooe/following{/other_user}","gists_url":"https://api.github.com/users/stevvooe/gists{/gist_id}","starred_url":"https://api.github.com/users/stevvooe/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/stevvooe/subscriptions","organizations_url":"https://api.github.com/users/stevvooe/orgs","repos_url":"https://api.github.com/users/stevvooe/repos","events_url":"https://api.github.com/users/stevvooe/events{/privacy}","received_events_url":"https://api.github.com/users/stevvooe/received_events","type":"User","site_admin":false},"milestone":{"url":"https://api.github.com/repos/docker/docker/milestones/37","html_url":"https://github.com/docker/docker/milestones/1.6.0","labels_url":"https://api.github.com/repos/docker/docker/milestones/37/labels","id":952335,"number":37,"title":"1.6.0","description":"","creator":{"login":"crosbymichael","id":749551,"avatar_url":"https://avatars.githubusercontent.com/u/749551?v=3","gravatar_id":"","url":"https://api.github.com/users/crosbymichael","html_url":"https://github.com/crosbymichael","followers_url":"https://api.github.com/users/crosbymichael/followers","following_url":"https://api.github.com/users/crosbymichael/following{/other_user}","gists_url":"https://api.github.com/users/crosbymichael/gists{/gist_id}","starred_url":"https://api.github.com/users/crosbymichael/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/crosbymichael/subscriptions","organizations_url":"https://api.github.com/users/crosbymichael/orgs","repos_url":"https://api.github.com/users/crosbymichael/repos","events_url":"https://api.github.com/users/crosbymichael/events{/privacy}","received_events_url":"https://api.github.com/users/crosbymichael/received_events","type":"User","site_admin":false},"open_issues":23,"closed_issues":13,"state":"open","created_at":"2015-01-26T23:40:13Z","updated_at":"2015-03-11T20:44:13Z","due_on":"2015-03-18T07:00:00Z","closed_at":null},"comments":99,"created_at":"2015-03-02T16:29:48Z","updated_at":"2015-03-13T19:53:19Z","closed_at":null,"pull_request":{"url":"https://api.github.com/repos/docker/docker/pulls/11109","html_url":"https://github.com/docker/docker/pull/11109","diff_url":"https://github.com/docker/docker/pull/11109.diff","patch_url":"https://github.com/docker/docker/pull/11109.patch"},"body":"# Overview\r\n\r\nWhen I create a container, I may specify an image such as `mysql:latest`. When the image is pulled, `latest` is resolved to a particular image at that point in time. If I later want to add more containers (e.g. possible read slaves in the MySQL case), all the new containers must use the exact same image as my first container. Using a tag isn't sufficient as the tag can be updated to point at a different image. We need a way to refer to images using immutable identifiers.\r\n\r\nWith the v2 image format, image manifests have content-addressable, immutable digests. The v2 registry supports retrieving manifests by digest; this pull request adds the corresponding support to the Docker Core.\r\n\r\n# Digest reference format\r\nWe'll need to provide a means to reference an image by its digest. I'd like to propose the following format:\r\n\r\n    namespace/repository@digest\r\n\r\n# Supported commands\r\n\r\nWe'll need to make sure the following commands continue to work as they currently do, as well as with an optional digest:\r\n\r\n- `docker build`\r\n- `docker pull`\r\n- `docker create`\r\n- `docker run`\r\n- `docker rmi`\r\n\r\nThis list should eventually be comprehensive; anywhere you can refer to an image, you should be able to do so by digest. For the time being, the commands listed above should be sufficient for the use case listed in the overview.\r\n\r\n# `docker images`\r\n\r\nIf you pull an image from a v2 registry, the registry provides the image manifest's digest as a response header. If you pull by tag, you'll have both the tag and the digest. If you pull only by digest, you won't have the tag information. 1 question to resolve is how to display images, tags, digests, and v1 image IDs in the `docker images` command.\r\n\r\nIt is possible (likely?) that a variety of code exists to scrape the output of `docker images`. If we change the format, e.g. by adding a new column, or overloading an existing column to sometimes show a v1 image ID vs a digest, we will probably break whatever code is out there doing the scraping. We need to determine how critical it is to retain the existing column and data formats in the `docker images` command.\r\n\r\nI have the following ideas regarding this output:\r\n\r\n- if an image was pulled by tag, and the registry it's pulled from includes the image's digest, display `repository`, `tag`, `digest`, and `image id`\r\n- if an image was pulled by digest, display `repository`, <none> for tag, `digest`, and `image id`\r\n\r\n## `docker images` questions\r\n\r\n- should we add a new `DIGEST` column?\r\n- if yes, should we always display it, or only display it if you indicate that you want to see digests (e.g. via a filter)\r\n    - there can be confusion if you pull an image by digest and then run `docker images` - you won't see the image you just pulled\r\n- should we display the digest instead of the v1 image ID (or some other value)?\r\n\r\n# Questions\r\n*What about v1 registry support?*\r\nThe v1 registry won't support this feature.\r\n\r\n*If I create an image locally via `docker tag` or `docker commit`, can I refer to it by `name@digest`?*\r\nAs proposed in https://github.com/docker/distribution/issues/46, the registry is responsible for determining an image's digest and assigning it to the image. For an image that has not yet been pushed to a v2 registry, it may not be possible to refer to it by `name@digest`. This is unlikely to be a significant issue, as the use case for `name@digest` is consistent deployments using images pulled from registries. Or, if the community thinks this should be supported, we can revisit what component(s) are responsible for calculating digests.\r\n\r\n# Additional information\r\nSee #10740 for more backstory.\r\n\r\nTodo:\r\n- [x] Test cases\r\n- [x] Update documentation"},"comment":{"url":"https://api.github.com/repos/docker/docker/issues/comments/79307738","html_url":"https://github.com/docker/docker/pull/11109#issuecomment-79307738","issue_url":"https://api.github.com/repos/docker/docker/issues/11109","id":79307738,"user":{"login":"moxiegirl","id":1347209,"avatar_url":"https://avatars.githubusercontent.com/u/1347209?v=3","gravatar_id":"","url":"https://api.github.com/users/moxiegirl","html_url":"https://github.com/moxiegirl","followers_url":"https://api.github.com/users/moxiegirl/followers","following_url":"https://api.github.com/users/moxiegirl/following{/other_user}","gists_url":"https://api.github.com/users/moxiegirl/gists{/gist_id}","starred_url":"https://api.github.com/users/moxiegirl/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/moxiegirl/subscriptions","organizations_url":"https://api.github.com/users/moxiegirl/orgs","repos_url":"https://api.github.com/users/moxiegirl/repos","events_url":"https://api.github.com/users/moxiegirl/events{/privacy}","received_events_url":"https://api.github.com/users/moxiegirl/received_events","type":"User","site_admin":false},"created_at":"2015-03-13T19:53:19Z","updated_at":"2015-03-13T19:53:19Z","body":"LGTM"}}