docker/docs: Document new data source + limitations (#7814)

d/registry_image.html.markdown

@@ -0,0 +1,40 @@
+---
+layout: "docker"
+page_title: "Docker: docker_registry_image"
+sidebar_current: "docs-docker-datasource-registry-image"
+description: |-
+  Finds the latest available sha256 digest for a docker image/tag from a registry.
+---
+
+# docker\_registry\_image
+
+-> **Note:** The initial (current) version of this data source can reliably read only **public** images **from the official Docker Hub Registry**.
+
+Reads the image metadata from a Docker Registry. Used in conjunction with the
+[docker\_image](/docs/providers/docker/r/image.html) resource to keep an image up
+to date on the latest available version of the tag.
+
+## Example Usage
+
+```
+data "docker_registry_image" "ubuntu" {
+    name = "ubuntu:precise"
+}
+
+resource "docker_image" "ubuntu" {
+    name = "${data.docker_image.ubuntu.name}"
+    pull_trigger = "${data.docker_registry_image.ubuntu.sha256_digest}"
+}
+```
+
+## Argument Reference
+
+The following arguments are supported:
+
+* `name` - (Required, string) The name of the Docker image, including any tags. e.g. `alpine:latest`
+
+## Attributes Reference
+
+The following attributes are exported in addition to the above configuration:
+
+* `id` (string) - The ID of the image, as stored on the registry.

index.html.markdown

@@ -41,6 +41,11 @@ resource "docker_image" "ubuntu" {
 }
 ```
 
+## Registry Credentials
+
+The initial (current) version of the Docker provider **doesn't** support registry authentication.
+This limits any use cases to public images for now.
+
 ## Argument Reference
 
 The following arguments are supported:

r/image.html.markdown

@@ -3,15 +3,18 @@ layout: "docker"
 page_title: "Docker: docker_image"
 sidebar_current: "docs-docker-resource-image"
 description: |-
-  Downloads and exports the ID of a Docker image.
+  Pulls a Docker image to a given Docker host.
 ---
 
 # docker\_image
 
-Downloads and exports the ID of a Docker image. This can be used alongside
-[docker\_container](/docs/providers/docker/r/container.html)
-to programmatically get the latest image IDs without having to hardcode
-them.
+-> **Note:** The initial (current) version of this resource can only pull **public** images **from the official Docker Hub Registry**.
+
+Pulls a Docker image to a given Docker host from a Docker Registry.
+
+This resource will *not* pull new layers of the image automatically unless used in
+conjuction with [`docker_registry_image`](/docs/providers/docker/d/registry_image.html)
+data source to update the `pull_trigger` field.
 
 ## Example Usage
 
@@ -24,18 +27,31 @@ resource "docker_image" "ubuntu" {
 # Access it somewhere else with ${docker_image.ubuntu.latest}
 ```
 
+### Dynamic image
+
+```
+data "docker_registry_image" "ubuntu" {
+    name = "ubuntu:precise"
+}
+
+resource "docker_image" "ubuntu" {
+    name = "${data.docker_registry_image.ubuntu.name}"
+    pull_trigger = "${data.docker_registry_image.ubuntu.sha256_digest}"
+}
+```
+
 ## Argument Reference
 
 The following arguments are supported:
 
 * `name` - (Required, string) The name of the Docker image, including any tags.
-* `keep_updated` - (Optional, boolean) If true, then the Docker image will
-  always be updated on the host to the latest. If this is false, as long as an
-  image is downloaded with the correct tag, it won't be redownloaded if
-  there is a newer image.
 * `keep_locally` - (Optional, boolean) If true, then the Docker image won't be
   deleted on destroy operation. If this is false, it will delete the image from
   the docker local storage on destroy operation.
+* `pull_trigger` - (Optional, string) Used to store the image digest from the
+  registry and will cause an image pull when changed. Needed when using
+  the `docker_registry_image` [data source](/docs/providers/docker/d/registry_image.html)
+  to trigger an update of the image.
 
 ## Attributes Reference