docs: improve terraform-hosted docs (#67)

once the usage instructions are on the terraform site, we should probably remove them from our README. Signed-off-by: Nick Santos <[email protected]>
docker · Oct 21, 2024 · 4b9ff42 · 4b9ff42
1 parent cb0aafb
commit 4b9ff42
Show file tree

Hide file tree

Showing 3 changed files with 189 additions and 0 deletions.
diff --git a/README.md b/README.md
@@ -6,6 +6,8 @@ teams, organization settings, and more) using Terraform.
 > [!WARNING]
 > This project is **not** for managing objects in a local docker engine. If you would like to use Terraform to interact with a docker engine, [kreuzwerker/docker](https://registry.terraform.io/providers/kreuzwerker/docker/latest) is a fine provider.
 
+Documentation: https://registry.terraform.io/providers/docker/docker/latest/docs
+
 ## Requirements
 
 - [Terraform](https://developer.hashicorp.com/terraform/downloads) >= 1.1

diff --git a/docs/index.md b/docs/index.md
@@ -3,12 +3,128 @@
 page_title: "docker Provider"
 subcategory: ""
 description: |-
+  Manage Docker-hosted resources (such as repositories,
+  teams, organization settings, and more) using Terraform.
+  [!WARNING]This project is not for managing objects in a local docker engine. If you would like to use Terraform to interact with a docker engine, kreuzwerker/docker is a fine provider.
+  Usage
+  Below is a basic example of how to use the Docker services Terraform provider to create a Docker repository.
   
+  terraform {
+    required_providers {
+      docker = {
+        source  = "docker/docker"
+        version = "~> 0.2"
+      }
+    }
+  }
+  
+  provider "docker" { }
+  
+  resource "docker_repository" "example" {
+    name        = "example-repo"
+    description = "This is an example Docker repository"
+    private     = true
+  }
+  
+  Authentication
+  We have multiple ways to set your Docker credentials.
+  Setting credentials
+  Use docker login to log in to aregistry https://docs.docker.com/reference/cli/docker/login/. The docker CLI
+  will store your credentials securely in your credential store, such as the
+  operating system native keychain. The Docker Terraform provider will
+  use these credentials automatically.
+  
+  cat ~/my_password.txt | docker login --username my-username --password-stdin
+  
+  If you'd like to use a different account for running the provider,
+  you can set credentials in the environment:
+  
+  export DOCKER_USERNAME=my-username
+  export DOCKER_PASSWORD=my-secret-token
+  terraform plan ...
+  
+  Credential types
+  You can create a personal access token (PAT) to use as an alternative to your
+  password for Docker CLI authentication.
+  A "Read, Write, & Delete" PAT can be used to create, edit, and
+  manage permissions for Docker Hub repositories.
+  The advantage of PATs is that they have many securitybenefits https://docs.docker.com/security/for-developers/access-tokens/ over
+  passwords.
+  Unfortunately, PATs are limited to managing repositories. If you'd like to use
+  this provider to manage organizations and teams, you will need to authenticate
 ---
 
 # docker Provider
 
+Manage Docker-hosted resources (such as repositories,
+teams, organization settings, and more) using Terraform.
+
+> [!WARNING]
+> This project is **not** for managing objects in a local docker engine. If you would like to use Terraform to interact with a docker engine, [kreuzwerker/docker](https://registry.terraform.io/providers/kreuzwerker/docker/latest) is a fine provider.
+
+## Usage
+
+Below is a basic example of how to use the Docker services Terraform provider to create a Docker repository.
+
+```hcl
+terraform {
+  required_providers {
+    docker = {
+      source  = "docker/docker"
+      version = "~> 0.2"
+    }
+  }
+}
+
+provider "docker" { }
+
+resource "docker_repository" "example" {
+  name        = "example-repo"
+  description = "This is an example Docker repository"
+  private     = true
+}
+```
+
+
+## Authentication
+
+We have multiple ways to set your Docker credentials.
+
+### Setting credentials
+
+Use `docker login` to [log in to a
+registry](https://docs.docker.com/reference/cli/docker/login/). The `docker` CLI
+will store your credentials securely in your credential store, such as the
+operating system native keychain. The Docker Terraform provider will
+use these credentials automatically.
+
+```
+cat ~/my_password.txt | docker login --username my-username --password-stdin
+```
+
+If you'd like to use a different account for running the provider,
+you can set credentials in the environment:
+
+```
+export DOCKER_USERNAME=my-username
+export DOCKER_PASSWORD=my-secret-token
+terraform plan ...
+```
+
+### Credential types
+
+You can create a personal access token (PAT) to use as an alternative to your
+password for Docker CLI authentication.
+
+A "Read, Write, & Delete" PAT can be used to create, edit, and
+manage permissions for Docker Hub repositories.
+
+The advantage of PATs is that they have [many security
+benefits](https://docs.docker.com/security/for-developers/access-tokens/) over
+passwords.
 
+Unfortunately, PATs are limited to managing repositories. If you'd like to use
+this provider to manage organizations and teams, you will need to authenticate
 
 
 

diff --git a/internal/provider/provider.go b/internal/provider/provider.go
@@ -70,6 +70,77 @@ func (p *DockerProvider) Metadata(ctx context.Context, req provider.MetadataRequ
 
 func (p *DockerProvider) Schema(ctx context.Context, req provider.SchemaRequest, resp *provider.SchemaResponse) {
 	resp.Schema = schema.Schema{
+		MarkdownDescription: `
+Manage Docker-hosted resources (such as repositories,
+teams, organization settings, and more) using Terraform.
+
+> [!WARNING]
+> This project is **not** for managing objects in a local docker engine. If you would like to use Terraform to interact with a docker engine, [kreuzwerker/docker](https://registry.terraform.io/providers/kreuzwerker/docker/latest) is a fine provider.
+
+## Usage
+
+Below is a basic example of how to use the Docker services Terraform provider to create a Docker repository.
+
+` + "```" + `hcl
+terraform {
+  required_providers {
+    docker = {
+      source  = "docker/docker"
+      version = "~> 0.2"
+    }
+  }
+}
+
+provider "docker" { }
+
+resource "docker_repository" "example" {
+  name        = "example-repo"
+  description = "This is an example Docker repository"
+  private     = true
+}
+` + "```" + `
+
+
+## Authentication
+
+We have multiple ways to set your Docker credentials.
+
+### Setting credentials
+
+Use ` + "`docker login`" + ` to [log in to a
+registry](https://docs.docker.com/reference/cli/docker/login/). The ` + "`docker`" + ` CLI
+will store your credentials securely in your credential store, such as the
+operating system native keychain. The Docker Terraform provider will
+use these credentials automatically.
+
+` + "```" + `
+cat ~/my_password.txt | docker login --username my-username --password-stdin
+` + "```" + `
+
+If you'd like to use a different account for running the provider,
+you can set credentials in the environment:
+
+` + "```" + `
+export DOCKER_USERNAME=my-username
+export DOCKER_PASSWORD=my-secret-token
+terraform plan ...
+` + "```" + `
+
+### Credential types
+
+You can create a personal access token (PAT) to use as an alternative to your
+password for Docker CLI authentication.
+
+A "Read, Write, & Delete" PAT can be used to create, edit, and
+manage permissions for Docker Hub repositories.
+
+The advantage of PATs is that they have [many security
+benefits](https://docs.docker.com/security/for-developers/access-tokens/) over
+passwords.
+
+Unfortunately, PATs are limited to managing repositories. If you'd like to use
+this provider to manage organizations and teams, you will need to authenticate
+`,
 		Attributes: map[string]schema.Attribute{
 			"host": schema.StringAttribute{
 				MarkdownDescription: "Docker Hub API Host. Default is `hub.docker.com`.",