diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 74309ec0..40f94caa 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -18,6 +18,11 @@ https://start.1password.com/integrations/active --> Connect Server Version: + +CLI Version: + OS: diff --git a/CHANGELOG.md b/CHANGELOG.md index 115197c8..f6208224 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -128,7 +128,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: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 687dc214..133d6b59 100644 --- a/CONTRIBUTING.md +++ b/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 \ No newline at end of file diff --git a/README.md b/README.md index 7c21becf..52fe4c3a 100644 --- a/README.md +++ b/README.md @@ -2,8 +2,8 @@
Use the 1Password Connect Terraform Provider to access and manage items in your 1Password vaults.
+Use the 1Password Terraform provider to access and manage items in your 1Password vaults.
diff --git a/docs/index.md b/docs/index.md index 48e18a15..9e437b9a 100644 --- a/docs/index.md +++ b/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. diff --git a/examples/provider/provider.tf b/examples/provider/provider.tf index 8939835c..201b4389 100644 --- a/examples/provider/provider.tf +++ b/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" } diff --git a/onepassword/provider.go b/onepassword/provider.go index af4595d7..5e4c5635 100644 --- a/onepassword/provider.go +++ b/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{ diff --git a/templates/index.md.tmpl b/templates/index.md.tmpl index cbed554c..10d7f7e1 100644 --- a/templates/index.md.tmpl +++ b/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.