Merge pull request #110 from 1Password/update-documentation-with-serv…

…ice-accounts

Update documentation with service accounts

.github/ISSUE_TEMPLATE/bug_report.md

@@ -18,6 +18,11 @@ https://start.1password.com/integrations/active
 -->
 Connect Server Version:
 
+<!-- What version of the OP CLI are you running?
+You can get this information by running 'op --version'
+-->
+CLI Version:
+
 <!-- What OS are you running Terraform on? -->
 OS:
 

CHANGELOG.md

@@ -140,7 +140,7 @@ Support custom sections and fields for Login, Password, and Database Items
 
 # v0.1.0
 
-Initial 1Password Connect Terraform Provider release
+Initial 1Password Terraform provider release
 
 ## Features:
 

CONTRIBUTING.md

@@ -1,10 +1,10 @@
 # Contributing
 
-Thanks for your interest in contributing to the 1Password Connect Terraform Provider project! 🙌 We appreciate your time and effort. Here are some guidelines to help you get started.
+Thanks for your interest in contributing to the 1Password Terraform provider project! 🙌 We appreciate your time and effort. Here are some guidelines to help you get started.
 
 ## Building
 
-Run the following command to build the 1Password Connect Terraform Provider:
+Run the following command to build the 1Password Terraform provider:
 
 ```sh
 go build .
@@ -20,16 +20,16 @@ To run the Go tests and check test coverage run the following command:
 go test -v ./... -cover
 ```
 
-## Installing plugin locally
+## Installing the provider locally
 
-Refer to the following sections of the Terraform's "Custom Framework Providers" tutorial to install this plugin locally:
+Refer to the following sections of the Terraform's "Custom Framework Providers" tutorial to install this provider locally:
 
 - [Prepare Terraform for local provider install](https://developer.hashicorp.com/terraform/tutorials/providers-plugin-framework/providers-plugin-framework-provider#prepare-terraform-for-local-provider-install)
 - [Locally install provider and verify with Terraform](https://developer.hashicorp.com/terraform/tutorials/providers-plugin-framework/providers-plugin-framework-provider#locally-install-provider-and-verify-with-terraform)
 
-## Using plugin locally
+## Using the provider locally
 
-In your Terraform configuration you will need to specify the `op` plugin with:
+You must specify the `onepassword` provider in your Terraform configuration:
 
 ```tf
 terraform {
@@ -46,9 +46,61 @@ provider "onepassword" {
 }
 ```
 
-After copying a newly-built version of the provider to the plugins directory you will have to run `terraform init` again. If you forget to do this then Terraform will error out and tell you to do so.
+After copying a newly built version of the provider to the plugins directory, you need to run `terraform init` again. Otherwise, Terraform returns an error.
 
-## Generating Documentation
+## Debugging
+
+To start debugging:
+
+1. Start a debugging session.
+2. Export `TF_REATTACH_PROVIDERS`.
+3. Run Terraform normally.
+
+
+### Start a debugging session
+
+You can start a debugging session in several ways:
+
+1. [Build the provider without optimizations](#build-the-provider-without-optimizations).
+2. [Start a debugging session](#start-a-debugging-session-1).
+
+**Note**: Before continuing, make sure you add the `dev_overrides` block to your `~/.terraformrc` file (using `"1Password/onepassword"` as the source). For instructions, refer to the [Installing the provider locally](#installing-the-provider-locally).
+
+#### Build the provider without optimizations
+
+Run the following command to build the provider without enabling optimizations:
+
+```sh
+go build -gcflags="all=-N -l" .
+```
+
+#### Start a debugging session
+
+Run the following command to start a Delve debugging session:
+
+```sh
+dlv debug . -- --debug
+```
+
+Or use your IDE debugger. You can configure editors like GoLand to start a debugging session by passing the `--debug` flag as a program argument.
+
+### Export `TF_REATTACH_PROVIDERS`
+
+If a debugging session was starts correctly, the provider prints the following output to `stdout`:
+
+```sh
+Provider started, to attach Terraform set the TF_REATTACH_PROVIDERS env var:
+
+    TF_REATTACH_PROVIDERS='{"1Password/onepassword":{"Protocol":"grpc","Pid":3382870,"Test":true,"Addr":{"Network":"unix","String":"/tmp/plugin713096927"}}}'
+```
+
+Copy the line starting with `TF_REATTACH_PROVIDERS` from your provider's output. You can either export this variable or prefix every Terraform command with it.
+
+### Run Terraform
+
+After starting a debugging session and exporting the `TF_REATTACH_PROVIDERS` variable, run Terraform as usual. Any breakpoints you have set will halt execution and show you the current variable values.
+
+## Generating documentation
 
 Documentation is generated for the provider using [terraform-plugin-docs](https://github.com/hashicorp/terraform-plugin-docs). This plugin uses the schema `Description` field in conjunction with the contents of the `/templates` and `/examples` folders to generate the `/docs` content.
 
@@ -57,3 +109,30 @@ To regenerate the `/docs` Markdown run:
 ```sh
 go generate
 ```
+
+## Sign your commits
+
+To get your PR merged, we require you to sign your commits.
+
+### Sign commits with `1Password`
+
+You can also sign commits using 1Password, which lets you sign commits with biometrics without the signing key leaving the local 1Password process.
+
+Learn how to use [1Password to sign your commits](https://developer.1password.com/docs/ssh/git-commit-signing/).
+
+
+### Sign commits with `ssh-agent`
+
+Follow the steps below to set up commit signing with `ssh-agent`:
+
+1. Generate an SSH key and add it to ssh-agent
+2. Add the SSH key to your GitHub account
+3. Configure git to use your SSH key for commit signing
+
+### Sign commits `gpg`
+
+Follow the steps below to set up commit signing with `gpg`:
+
+1. Generate a GPG key
+2. Add the GPG key to your GitHub account
+3. Configure git to use your GPG key for commit signing

README.md

@@ -2,8 +2,8 @@
 <img alt="" role="img" src="https://blog.1password.com/posts/2021/secrets-automation-launch/header.svg"/>
 
 <div align="center">
-  <h1>1Password Connect Terraform Provider</h1>
-  <p>Use the 1Password Connect Terraform Provider to access and manage items in your 1Password vaults.</p>
+  <h1>1Password Terraform provider</h1>
+  <p>Use the 1Password Terraform provider to access and manage items in your 1Password vaults.</p>
   <a href="#-get-started">
     <img alt="Get started" src="https://user-images.githubusercontent.com/45081667/226940040-16d3684b-60f4-4d95-adb2-5757a8f1bc15.png" height="37"/>
   </a>

docs/index.md

@@ -2,25 +2,26 @@
 layout: ""
 page_title: "Provider: 1Password"
 description: |-
-  Use the 1Password Connect Terraform Provider to reference, create, or update logins, password and database items in your 1Password Vaults.
+  Use the 1Password Terraform provider to reference, create, or update logins, passwords, and database items in your 1Password vaults.
 ---
 
-# 1Password Connect Terraform Provider
+# 1Password Terraform provider
 
-Use the 1Password Connect Terraform Provider to reference, create, or update items in your existing vaults using [1Password Secrets Automation](https://1password.com/secrets).
+Use the 1Password Terraform provider to reference, create, or update items in your existing vaults using [1Password Secrets Automation](https://1password.com/secrets).
 
-## Using a Service Account Token
-
-The 1Password Connect Terraform Provider supports both the [1Password Connect Server](https://developer.1password.com/docs/secrets-automation/#1password-connect-server)
-and [1Password Service Accounts](https://developer.1password.com/docs/secrets-automation/#1password-service-accounts). To use a service account token, the
-[1Password CLI](https://developer.1password.com/docs/cli) has to be installed on the machine running terraform. For how to do this in terraform cloud, see
-[here](https://developer.hashicorp.com/terraform/cloud-docs/run/install-software#only-install-standalone-binaries).
+The 1Password Terraform provider supports using both [1Password Connect Server](https://developer.1password.com/docs/secrets-automation/#1password-connect-server)
+and [1Password Service Accounts](https://developer.1password.com/docs/secrets-automation/#1password-service-accounts).
+To use a service account token, you must install [1Password CLI](https://developer.1password.com/docs/cli) on the machine running Terraform. 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.
 
 ## Example Usage
 
 ```terraform
 provider "onepassword" {
-  url = "http://localhost:8080"
+  url                   = "http://localhost:8080"
+  token                 = "CONNECT_TOKEN"
+  service_account_token = "SERVICE_ACCOUNT_TOKEN"
+  op_cli_path           = "OP_CLI_PATH"
 }
 ```
 
@@ -33,3 +34,20 @@ provider "onepassword" {
 - `service_account_token` (String) A valid token for your 1Password Service Account. Can also be sourced from OP_SERVICE_ACCOUNT_TOKEN. Either this or `token` must be set.
 - `token` (String) A valid token for your 1Password Connect API. Can also be sourced from OP_CONNECT_TOKEN. Either this or `service_account_token` must be set.
 - `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. Can be omitted, if service_account_token is set.
+
+## Known Service Accounts limitation:
+Users might encounter the following error if they create, update, or delete too many items simultaneously in the same 1Password vault.
+
+\```
+op error: (409) Conflict: Internal server conflict
+\```
+
+The 1Password Terraform provider handles each resource separately. As a result, each request to perform a create, update, or delete operation using CLI to create an additional parallel request. Too many parallel requests might result in one or more race conditions.
+
+You can avoid receiving the 409 error in one of the following ways:
+1. Use `depends_on` in your resource definition to make sure the provider makes requests sequentially.
+2. After receiving the `409` error, run `terraform apply` again. You might need to run this multiple times until it applies all the changes.
+3. Use a Connect server.
+4. Put items in the different vaults.
+
+This will be addressed in the future release.

examples/provider/provider.tf

@@ -1,3 +1,6 @@
 provider "onepassword" {
-  url = "http://localhost:8080"
+  url                   = "http://localhost:8080"
+  token                 = "CONNECT_TOKEN"
+  service_account_token = "SERVICE_ACCOUNT_TOKEN"
+  op_cli_path           = "OP_CLI_PATH"
 }

onepassword/provider.go

@@ -35,7 +35,7 @@ func init() {
 	// }
 }
 
-// Provider The 1Password Connect terraform provider
+// Provider The 1Password Terraform provider
 func Provider() *schema.Provider {
 	providerUserAgent := fmt.Sprintf(terraformProviderUserAgent, version.ProviderVersion)
 	provider := &schema.Provider{

templates/index.md.tmpl

@@ -2,22 +2,37 @@
 layout: ""
 page_title: "Provider: 1Password"
 description: |-
-  Use the 1Password Connect Terraform Provider to reference, create, or update logins, password and database items in your 1Password Vaults.
+  Use the 1Password Terraform provider to reference, create, or update logins, passwords, and database items in your 1Password vaults.
 ---
 
-# 1Password Connect Terraform Provider
+# 1Password Terraform provider
 
-Use the 1Password Connect Terraform Provider to reference, create, or update items in your existing vaults using [1Password Secrets Automation](https://1password.com/secrets).
+Use the 1Password Terraform provider to reference, create, or update items in your existing vaults using [1Password Secrets Automation](https://1password.com/secrets).
 
-## Using a Service Account Token
-
-The 1Password Connect Terraform Provider supports both the [1Password Connect Server](https://developer.1password.com/docs/secrets-automation/#1password-connect-server)
-and [1Password Service Accounts](https://developer.1password.com/docs/secrets-automation/#1password-service-accounts). To use a service account token, the
-[1Password CLI](https://developer.1password.com/docs/cli) has to be installed on the machine running terraform. For how to do this in terraform cloud, see
-[here](https://developer.hashicorp.com/terraform/cloud-docs/run/install-software#only-install-standalone-binaries).
+The 1Password Terraform provider supports using both [1Password Connect Server](https://developer.1password.com/docs/secrets-automation/#1password-connect-server)
+and [1Password Service Accounts](https://developer.1password.com/docs/secrets-automation/#1password-service-accounts).
+To use a service account token, you must install [1Password CLI](https://developer.1password.com/docs/cli) on the machine running Terraform. 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.
 
 ## Example Usage
 
 {{tffile "examples/provider/provider.tf"}}
 
 {{ .SchemaMarkdown | trimspace }}
+
+## Known Service Accounts limitation:
+Users might encounter the following error if they create, update, or delete too many items simultaneously in the same 1Password vault.
+
+\```
+op error: (409) Conflict: Internal server conflict
+\```
+
+The 1Password Terraform provider handles each resource separately. As a result, each request to perform a create, update, or delete operation using CLI to create an additional parallel request. Too many parallel requests might result in one or more race conditions.
+
+You can avoid receiving the 409 error in one of the following ways:
+1. Use `depends_on` in your resource definition to make sure the provider makes requests sequentially.
+2. After receiving the `409` error, run `terraform apply` again. You might need to run this multiple times until it applies all the changes.
+3. Use a Connect server.
+4. Put items in the different vaults.
+
+This will be addressed in the future release.