Merge pull request #121 from 1Password/update-documentation

Update documentation
1Password · Dec 12, 2023 · f1958d9 · f1958d9
2 parents d5367ac + 65f8662
commit f1958d9
Show file tree

Hide file tree

Showing 6 changed files with 86 additions and 25 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -42,7 +42,7 @@ terraform {
 }
 
 provider "onepassword" {
-  url = "http://<1Password Connect API Hostname>"
+  service_account_token = "<1Password service account token>"
 }
 ```
 

diff --git a/README.md b/README.md
@@ -27,7 +27,7 @@ terraform {
 }
 
 provider "onepassword" {
-  url = "http://localhost:8080"
+  service_account_token = "<1Password service account token>"
 }
 
 variable "vault_id" {}

diff --git a/docs/index.md b/docs/index.md
@@ -17,6 +17,8 @@ You must install [1Password CLI](https://developer.1password.com/docs/cli) on th
 
 ## Use with 1Password CLI
 
+:warning: Minimum [1Password CLI version](https://app-updates.agilebits.com/product_history/CLI2) `v2.23.0` is required.
+
 Retry mechanism is implemented when using the provider with 1Password CLI. The reason for having a retry mechanism is that 1Password doesn't allow parallel modification on the items located in the same vault.
 Note that each retry fast forwards to the [service account rate limit](https://developer.1password.com/docs/service-accounts/rate-limits/) if use with service account.
 
@@ -27,7 +29,9 @@ terraform apply `-parallelism=n`
 
 ### Authenticate CLI with service account
 
-To authenticate CLI with service account, set `service_account_token` in the provider configuration.
+To authenticate CLI with service account:
+1. [Create a service account](https://developer.1password.com/docs/service-accounts/get-started#create-a-service-account)
+2. Set `OP_SERVICE_ACCOUNT_TOKEN` environment variable or `service_account_token` in the provider configuration.
 
 ### Authenticate the CLI with user account using biometric unlock
 
@@ -39,14 +43,15 @@ URL                        EMAIL                                         USER ID
 acme.dev.com               [email protected]                            HERE_WILL_BE_REAL_USER_ID
 acme.prod.com              [email protected]                            HERE_WILL_BE_REAL_USER_ID
 ```
-3. Set `account` in the provider configuration with the `URL` or `USER ID` value from the previous step.
+3. Set `OP_ACCOUNT` environment variable or `account` in the provider configuration with the `URL` or `USER ID` value from the previous step.
 4. When the biometric unlock popup appears while running terraform command, [authenticate it using fingerprint or password](https://developer.1password.com/docs/cli/app-integration/#step-2-enter-any-command-to-sign-in).
 
 ## Use with 1Password Connect
 
 To use the provider with 1Password Connect you need to
 1. [Deploy your Connect server](https://developer.1password.com/docs/connect/get-started#deployment)
-2. Set `url` and `token` in the provider configuration.
+2. Set `OP_CONNECT_HOST` environment variable or `url` in the provider configuration.
+3. Set `OP_CONNECT_TOKEN` environment variable or `token` in the provider configuration.
 
 ## Example Usage
 
@@ -60,13 +65,22 @@ provider "onepassword" {
 }
 ```
 
+You can set each of the configuration options using environment variables.
+Environment variables are a more secure way to set configuration options because they prevent accidentally pushing sensitive values to the project repo.
+
+- `OP_CONNECT_HOST` - The URL where your 1Password Connect API can be found.
+- `OP_CONNECT_TOKEN` - A valid token for your 1Password Connect API.
+- `OP_SERVICE_ACCOUNT_TOKEN` - A valid 1Password service account token to use with 1Password CLI
+- `OP_ACCOUNT` - A valid account's sign-in address or ID to use with 1Password CLI and biometrics unlock.
+- `OP_CLI_PATH` - The path to the 1Password CLI binary.
+
 <!-- schema generated by tfplugindocs -->
 ## Schema
 
 ### Optional
 
-- `account` (String) A valid account's sign-in address or ID to use biometrics unlock. Can also be sourced from OP_ACCOUNT. Must be set to use with biometric unlock.
-- `op_cli_path` (String) The path to the 1Password CLI binary. Can also be sourced from OP_CLI_PATH. Defaults to `op`.
-- `service_account_token` (String) A valid token for your 1Password Service Account. Can also be sourced from OP_SERVICE_ACCOUNT_TOKEN. Must be set to use with 1Password service account.
-- `token` (String) A valid token for your 1Password Connect API. Can also be sourced from OP_CONNECT_TOKEN. Must be set to use with 1Password Connect server.
-- `url` (String) The HTTP(S) URL where your 1Password Connect API can be found. Must be provided through the OP_CONNECT_HOST environment variable if this attribute is not set. Must be set to use with 1Password Connect server.
+- `account` (String) A valid account's sign-in address or ID to use biometrics unlock. Can also be sourced from `OP_ACCOUNT` environment variable. Provider will use the 1Password CLI if set.
+- `op_cli_path` (String) The path to the 1Password CLI binary. Can also be sourced from `OP_CLI_PATH` environment variable. Defaults to `op`.
+- `service_account_token` (String) A valid 1Password service account token. Can also be sourced from `OP_SERVICE_ACCOUNT_TOKEN` environment variable. Provider will use the 1Password CLI if set.
+- `token` (String) A valid token for your 1Password Connect server. Can also be sourced from `OP_CONNECT_TOKEN` environment variable. Provider will use 1Password Connect server if set.
+- `url` (String) The HTTP(S) URL where your 1Password Connect server can be found. Can also be sourced `OP_CONNECT_HOST` environment variable. Provider will use 1Password Connect server if set.
diff --git a/examples/README.md b/examples/README.md
@@ -3,16 +3,49 @@
 This example demonstrates creating the currently supported types of 1Password Items (Logins, Passwords, and Databases).
 ## Prerequisites
 
-To run this example you have to have either issue a 1Password service account token or setup a 1Password Connect API instance and issued a Connect Token with access to a demo vault. You will need to export both the Connect API token and the UUID of your demo vault as environment variables.
+The 1Password Terraform provider supports using both [1Password Connect Server](https://developer.1password.com/docs/secrets-automation/#1password-connect-server)
+and [1Password CLI](https://developer.1password.com/docs/cli).
 
-```sh
-# to use service account, set
-$ export OP_SERVICE_ACCOUNT_TOKEN="Put your 1Password service account token here"
+You must install [1Password CLI](https://developer.1password.com/docs/cli) on the machine running Terraform to use it. Refer to the
+[Terraform documentation](https://developer.hashicorp.com/terraform/cloud-docs/run/install-software#only-install-standalone-binaries) to learn how to install 1Password CLI on Terraform Cloud.
+
+## Use with 1Password CLI
+
+Minimum 1Password CLI version `v2.23.0` is required.
+
+Retry mechanism is implemented when using the provider with 1Password CLI. The reason for having a retry mechanism is that 1Password doesn't allow parallel modification on the items located in the same vault.
+Note that each retry fast forwards to the [service account rate limit](https://developer.1password.com/docs/service-accounts/rate-limits/) if use with service account.
 
-# to use Connect, set
-$ export OP_CONNECT_TOKEN="Put your 1Password Connect API token here"
-$ export TF_VAR_demo_vault="Put a Vault UUID that has been added to your 1Password Connect API here"
+It's recommended to limit the number of parallel resource operations. It can be done by using `-parallelism=n` flag when running `terraform apply`, where `n` is the number of parallel resource operations (the default is `10`).
 ```
+terraform apply `-parallelism=n`
+```
+
+### Authenticate CLI with service account
+
+To authenticate CLI with service account:
+1. [Create a service account](https://developer.1password.com/docs/service-accounts/get-started#create-a-service-account)
+2. Set `OP_SERVICE_ACCOUNT_TOKEN` environment variable or `service_account_token` in the provider configuration.
+
+### Authenticate the CLI with user account using biometric unlock
+
+To authenticate the CLI with user account using biometric unlock:
+1. [Turn on the app integration](https://developer.1password.com/docs/cli/app-integration/#step-1-turn-on-the-app-integration)
+2. In the terminal run `op account ls` to find sign-in address or account ID. It will print similar output in the console:
+```
+URL                        EMAIL                                         USER ID
+acme.dev.com               [email protected]                            HERE_WILL_BE_REAL_USER_ID
+acme.prod.com              [email protected]                            HERE_WILL_BE_REAL_USER_ID
+```
+3. Set `OP_ACCOUNT` environment variable or `account` in the provider configuration with the `URL` or `USER ID` value from the previous step.
+4. When the biometric unlock popup appears while running terraform command, [authenticate it using fingerprint or password](https://developer.1password.com/docs/cli/app-integration/#step-2-enter-any-command-to-sign-in).
+
+## Use with 1Password Connect
+
+To use the provider with 1Password Connect you need to
+1. [Deploy your Connect server](https://developer.1password.com/docs/connect/get-started#deployment)
+2. Set `OP_CONNECT_HOST` environment variable or `url` in the provider configuration.
+3. Set `OP_CONNECT_TOKEN` environment variable or `token` in the provider configuration.
 
 ## Create the Items
 

diff --git a/onepassword/provider.go b/onepassword/provider.go
@@ -44,31 +44,31 @@ func Provider() *schema.Provider {
 				Type:        schema.TypeString,
 				Optional:    true,
 				DefaultFunc: schema.EnvDefaultFunc("OP_CONNECT_HOST", nil),
-				Description: "The HTTP(S) URL where your 1Password Connect API can be found. Must be provided through the OP_CONNECT_HOST environment variable if this attribute is not set. Must be set to use with 1Password Connect server.",
+				Description: "The HTTP(S) URL where your 1Password Connect server can be found. Can also be sourced `OP_CONNECT_HOST` environment variable. Provider will use 1Password Connect server if set.",
 			},
 			"token": {
 				Type:        schema.TypeString,
 				Optional:    true,
 				DefaultFunc: schema.EnvDefaultFunc("OP_CONNECT_TOKEN", nil),
-				Description: "A valid token for your 1Password Connect API. Can also be sourced from OP_CONNECT_TOKEN. Must be set to use with 1Password Connect server.",
+				Description: "A valid token for your 1Password Connect server. Can also be sourced from `OP_CONNECT_TOKEN` environment variable. Provider will use 1Password Connect server if set.",
 			},
 			"service_account_token": {
 				Type:        schema.TypeString,
 				Optional:    true,
 				DefaultFunc: schema.EnvDefaultFunc("OP_SERVICE_ACCOUNT_TOKEN", nil),
-				Description: "A valid token for your 1Password Service Account. Can also be sourced from OP_SERVICE_ACCOUNT_TOKEN. Must be set to use with 1Password service account.",
+				Description: "A valid 1Password service account token. Can also be sourced from `OP_SERVICE_ACCOUNT_TOKEN` environment variable. Provider will use the 1Password CLI if set.",
 			},
 			"account": {
 				Type:        schema.TypeString,
 				Optional:    true,
 				DefaultFunc: schema.EnvDefaultFunc("OP_ACCOUNT", nil),
-				Description: "A valid account's sign-in address or ID to use biometrics unlock. Can also be sourced from OP_ACCOUNT. Must be set to use with biometric unlock.",
+				Description: "A valid account's sign-in address or ID to use biometrics unlock. Can also be sourced from `OP_ACCOUNT` environment variable. Provider will use the 1Password CLI if set.",
 			},
 			"op_cli_path": {
 				Type:        schema.TypeString,
 				Optional:    true,
 				DefaultFunc: schema.EnvDefaultFunc("OP_CLI_PATH", "op"),
-				Description: "The path to the 1Password CLI binary. Can also be sourced from OP_CLI_PATH. Defaults to `op`.",
+				Description: "The path to the 1Password CLI binary. Can also be sourced from `OP_CLI_PATH` environment variable. Defaults to `op`.",
 			},
 		},
 		DataSourcesMap: map[string]*schema.Resource{

diff --git a/templates/index.md.tmpl b/templates/index.md.tmpl
@@ -17,6 +17,8 @@ You must install [1Password CLI](https://developer.1password.com/docs/cli) on th
 
 ## Use with 1Password CLI
 
+:warning: Minimum [1Password CLI version](https://app-updates.agilebits.com/product_history/CLI2) `v2.23.0` is required.
+
 Retry mechanism is implemented when using the provider with 1Password CLI. The reason for having a retry mechanism is that 1Password doesn't allow parallel modification on the items located in the same vault.
 Note that each retry fast forwards to the [service account rate limit](https://developer.1password.com/docs/service-accounts/rate-limits/) if use with service account.
 
@@ -27,7 +29,9 @@ terraform apply `-parallelism=n`
 
 ### Authenticate CLI with service account
 
-To authenticate CLI with service account, set `service_account_token` in the provider configuration.
+To authenticate CLI with service account:
+1. [Create a service account](https://developer.1password.com/docs/service-accounts/get-started#create-a-service-account)
+2. Set `OP_SERVICE_ACCOUNT_TOKEN` environment variable or `service_account_token` in the provider configuration.
 
 ### Authenticate the CLI with user account using biometric unlock
 
@@ -39,17 +43,27 @@ URL                        EMAIL                                         USER ID
 acme.dev.com               [email protected]                            HERE_WILL_BE_REAL_USER_ID
 acme.prod.com              [email protected]                            HERE_WILL_BE_REAL_USER_ID
 ```
-3. Set `account` in the provider configuration with the `URL` or `USER ID` value from the previous step.
+3. Set `OP_ACCOUNT` environment variable or `account` in the provider configuration with the `URL` or `USER ID` value from the previous step.
 4. When the biometric unlock popup appears while running terraform command, [authenticate it using fingerprint or password](https://developer.1password.com/docs/cli/app-integration/#step-2-enter-any-command-to-sign-in).
 
 ## Use with 1Password Connect
 
 To use the provider with 1Password Connect you need to
 1. [Deploy your Connect server](https://developer.1password.com/docs/connect/get-started#deployment)
-2. Set `url` and `token` in the provider configuration.
+2. Set `OP_CONNECT_HOST` environment variable or `url` in the provider configuration.
+3. Set `OP_CONNECT_TOKEN` environment variable or `token` in the provider configuration.
 
 ## Example Usage
 
 {{tffile "examples/provider/provider.tf"}}
 
+You can set each of the configuration options using environment variables.
+Environment variables are a more secure way to set configuration options because they prevent accidentally pushing sensitive values to the project repo.
+
+- `OP_CONNECT_HOST` - The URL where your 1Password Connect API can be found.
+- `OP_CONNECT_TOKEN` - A valid token for your 1Password Connect API.
+- `OP_SERVICE_ACCOUNT_TOKEN` - A valid 1Password service account token to use with 1Password CLI
+- `OP_ACCOUNT` - A valid account's sign-in address or ID to use with 1Password CLI and biometrics unlock.
+- `OP_CLI_PATH` - The path to the 1Password CLI binary.
+
 {{ .SchemaMarkdown | trimspace }}