diff --git a/docker/resource_docker_container.go b/docker/resource_docker_container.go
index f8932b8a..70b87c62 100644
--- a/docker/resource_docker_container.go
+++ b/docker/resource_docker_container.go
@@ -284,11 +284,12 @@ func resourceDockerContainer() *schema.Resource {
 			},
 
 			"links": &schema.Schema{
-				Type:     schema.TypeSet,
-				Optional: true,
-				ForceNew: true,
-				Elem:     &schema.Schema{Type: schema.TypeString},
-				Set:      schema.HashString,
+				Type:       schema.TypeSet,
+				Optional:   true,
+				ForceNew:   true,
+				Elem:       &schema.Schema{Type: schema.TypeString},
+				Set:        schema.HashString,
+				Deprecated: "The --link flag is a legacy feature of Docker. It may eventually be removed.",
 			},
 
 			"ip_address": &schema.Schema{
diff --git a/website/docs/r/container.html.markdown b/website/docs/r/container.html.markdown
index 9bc64ae8..c000a195 100644
--- a/website/docs/r/container.html.markdown
+++ b/website/docs/r/container.html.markdown
@@ -53,6 +53,12 @@ The following arguments are supported:
   container.
 * `links` - (Optional, set of strings) Set of links for link based
   connectivity between containers that are running on the same host.
+
+~> **Warning** The --link flag is a legacy feature of Docker. It may eventually
+be removed. It exposes _all_ environment variables originating from Docker to
+any linked containers. This could have serious security implications if sensitive
+data is stored in them. See [the docker documentation][linkdoc] for more details.
+
 * `hostname` - (Optional, string) Hostname of the container.
 * `domainname` - (Optional, string) Domain name of the container.
 * `restart` - (Optional, string) The restart policy for the container. Must be
@@ -205,3 +211,6 @@ The following attributes are exported:
    NetworkSettings.
  * `bridge` - The network bridge of the container as read from its
    NetworkSettings.
+
+
+[linkdoc] https://docs.docker.com/network/links/
\ No newline at end of file