AWS install resources (#5)

**Add support for AWS install: iam-write**

Adds support for completing an AWS installation on P0, as well as
documents
how to integrate this resource with appropriate AWS-provider resource
blocks.

**Add contributing details**

Adds useful information for contributors to get started with local
testing.

**Add support for installing AWS: staging**

This commit
- Moves some common resource operations to shared code
- Adds support for staging an AWS account for installation

CONTRIBUTING.md

@@ -0,0 +1,54 @@
+## Local testing
+
+To test with the P0 Terraform provider, add the following to your `.terraformrc`:
+
+```hcl
+provider_installation {
+
+  dev_overrides {
+      "hashicorp.com/p0-security/p0" = "/path/to/godir/go/bin"
+  }
+
+  # For all other providers, install them directly from their origin provider
+  # registries as normal. If you omit this, Terraform will _only_ use
+  # the dev_overrides block, and so no other providers will be available.
+  direct {}
+}
+```
+
+Then, create a `examples/provider-install-verification` directory in this
+repository (this path is permanently added to `.gitignore`), and add a `main.tf`:
+
+```hcl
+terraform {
+  required_providers {
+    p0 = {
+      source = "hashicorp.com/p0-security/p0"
+    }
+  }
+}
+
+provider "p0" {
+  org = "p0-nathan"
+}
+```
+
+Now, build this provider:
+
+```bash
+go install
+```
+
+You can now test locally. In the `examples/provider-install-verification` directory:
+
+```bash
+export P0_API_TOKEN=...
+terraform plan
+```
+
+If you are using a local build of the P0 API server, you can also set that in your
+environment:
+
+```bash
+export P0_HOST=...
+```

docs/resources/aws_iam_write.md

@@ -0,0 +1,194 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "p0_aws_iam_write Resource - p0"
+subcategory: ""
+description: |-
+  An AWS installation.
+  Important: This resource should be used together with the 'awsstaged' resource, with a dependency chain
+  requiring this resource to be updated after the 'awsstaged' resource.
+  P0 recommends you use these resources according to the following pattern:
+  ```
+  resource "p0awsstaged" "staged_account" {
+    id         = ...
+    components = ["iam-write"]
+  }
+  See current P0 docs for the appropriate input in this block
+  resource "awsiampolicy" "p0iammanager" {
+    ...
+  }
+  resource "awsiamrole" "p0iammanager" {
+    name               = "P0RoleIamManager"
+    assumerolepolicy = jsonencode({
+      Version = "2012-10-17"
+      Statement = [
+        {
+          Effect = "Allow"
+          Principal = {
+            Federated = "accounts.google.com"
+          }
+          Action = "sts:AssumeRoleWithWebIdentity"
+          Condition = {
+            StringEquals = {
+              "accounts.google.com:aud" = "${p0awsstaged.stagedaccount.serviceaccountid}"
+            }
+          }
+        }
+      ]
+    })
+    managedpolicyarns = [awsiampolicy.p0iam_manager.arn]
+  }
+  resource "p0awsiamwrite" "installedaccount" {
+    id         = p0awsstaged.stagedaccount.id
+    dependson = [awsiamrole.p0iammanager]
+    ...
+  }
+  ```
+---
+
+# p0_aws_iam_write (Resource)
+
+An AWS installation.
+
+**Important**: This resource should be used together with the 'aws_staged' resource, with a dependency chain
+requiring this resource to be updated after the 'aws_staged' resource.
+
+P0 recommends you use these resources according to the following pattern:
+
+```
+resource "p0_aws_staged" "staged_account" {
+  id         = ...
+  components = ["iam-write"]
+}
+
+# See current P0 docs for the appropriate input in this block
+resource "aws_iam_policy" "p0_iam_manager" {
+  ...
+}
+
+resource "aws_iam_role" "p0_iam_manager" {
+  name               = "P0RoleIamManager"
+  assume_role_policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [
+      {
+        Effect = "Allow"
+        Principal = {
+          Federated = "accounts.google.com"
+        }
+        Action = "sts:AssumeRoleWithWebIdentity"
+        Condition = {
+          StringEquals = {
+            "accounts.google.com:aud" = "${p0_aws_staged.staged_account.service_account_id}"
+          }
+        }
+      }
+    ]
+  })
+  managed_policy_arns = [aws_iam_policy.p0_iam_manager.arn]
+}
+
+resource "p0_aws_iam_write" "installed_account" {
+  id         = p0_aws_staged.staged_account.id
+  depends_on = [aws_iam_role.p0_iam_manager]
+  ...
+}
+```
+
+## Example Usage
+
+```terraform
+resource "p0_aws_iam_write" "example" {
+  id         = p0_aws_staged.example.id
+  depends_on = [p0_aws_staged.example]
+  login = {
+    type = "iam"
+    identity = {
+      type = "email"
+    }
+  }
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `id` (String) The AWS account ID
+- `login` (Attributes) How users log in to this AWS account (see [below for nested schema](#nestedatt--login))
+
+### Optional
+
+- `label` (String) The AWS account's alias (if available)
+
+### Read-Only
+
+- `state` (String) This account's install progress in the P0 application:
+		- 'stage': The account has been staged for installation
+		- 'configure': The account is available to be added to P0, and may be configured
+		- 'installed': The account is fully installed
+
+<a id="nestedatt--login"></a>
+### Nested Schema for `login`
+
+Required:
+
+- `type` (String) One of:
+    - 'iam': Users log in as IAM users; 'identity' attribute is required
+    - 'idc': Users log in via Identity Center (formerly 'SSO'); 'parent' attribute is required
+    - 'federated': Users log in via a federated identity provider; 'provider' attribute is required
+
+Optional:
+
+- `identity` (Attributes) How user identities are mapped to AWS IAM users (see [below for nested schema](#nestedatt--login--identity))
+- `parent` (String) Identity Center parent account ID
+- `provider` (Attributes) Federated login provider details (see [below for nested schema](#nestedatt--login--provider))
+
+<a id="nestedatt--login--identity"></a>
+### Nested Schema for `login.identity`
+
+Required:
+
+- `type` (String) One of:
+    - 'email': IAM user names are user email addresses
+    - 'tag': User email addresses appear in IAM user tag; 'tag_name' is required
+
+Optional:
+
+- `tag_name` (String) The name of the AWS user tag that holds the user's email address
+
+
+<a id="nestedatt--login--provider"></a>
+### Nested Schema for `login.provider`
+
+Required:
+
+- `app_id` (String) Okta AWS federation app ID
+- `identity_provider` (String) AWS provider integration; this is the _name_ of the AWS integration that you use for federated login,
+defined on the ["Identity providers" tab](https://console.aws.amazon.com/iam/home#/identity_providers) of your IAM dashboard
+- `method` (Attributes) The federation method used by your identity provider (see [below for nested schema](#nestedatt--login--provider--method))
+
+Optional:
+
+- `type` (String) Only 'okta' is supported at this time
+
+<a id="nestedatt--login--provider--method"></a>
+### Nested Schema for `login.provider.method`
+
+Required:
+
+- `account_count` (Attributes) Number of AWS accounts linked to the federation app:
+    - 'single': One account only
+    - 'multi': Multiple accounts, via a parent account (see [below for nested schema](#nestedatt--login--provider--method--account_count))
+
+Optional:
+
+- `type` (String) Only 'saml' is supported at this time
+
+<a id="nestedatt--login--provider--method--account_count"></a>
+### Nested Schema for `login.provider.method.type`
+
+Optional:
+
+- `parent` (String) The account ID of the federation app's parent AWS account
+- `type` (String)

docs/resources/aws_staged.md

@@ -0,0 +1,36 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "p0_aws_staged Resource - p0"
+subcategory: ""
+description: |-
+  A staged AWS installation. Staged resources are used to generate AWS trust policies.
+  Important Before using this resource, please read the instructions for the 'awsiamwrite' resource.
+---
+
+# p0_aws_staged (Resource)
+
+A staged AWS installation. Staged resources are used to generate AWS trust policies.
+
+**Important** Before using this resource, please read the instructions for the 'aws_iam_write' resource.
+
+## Example Usage
+
+```terraform
+resource "p0_aws_staged" "example" {
+  id         = "123456789012"
+  components = ["iam-write"]
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `components` (Set of String) Components to install (any of "iam-write", "inventory")
+- `id` (String) The AWS account ID
+
+### Read-Only
+
+- `label` (String) The AWS account's alias (if available)
+- `service_account_id` (String) The audience ID of the service account to include in this AWS account's P0 role trust policies

examples/resources/p0_aws_iam_write/resource.tf

@@ -0,0 +1,10 @@
+resource "p0_aws_iam_write" "example" {
+  id         = p0_aws_staged.example.id
+  depends_on = [p0_aws_staged.example]
+  login = {
+    type = "iam"
+    identity = {
+      type = "email"
+    }
+  }
+}

examples/resources/p0_aws_staged/resource.tf

@@ -0,0 +1,4 @@
+resource "p0_aws_staged" "example" {
+  id         = "123456789012"
+  components = ["iam-write"]
+}

go.mod

@@ -5,6 +5,7 @@ go 1.21
 require (
 	github.com/hashicorp/terraform-plugin-docs v0.18.0
 	github.com/hashicorp/terraform-plugin-framework v1.7.0
+	github.com/hashicorp/terraform-plugin-framework-validators v0.12.0
 )
 
 require (

go.sum

@@ -83,6 +83,8 @@ github.com/hashicorp/terraform-plugin-docs v0.18.0 h1:2bINhzXc+yDeAcafurshCrIjtd
 github.com/hashicorp/terraform-plugin-docs v0.18.0/go.mod h1:iIUfaJpdUmpi+rI42Kgq+63jAjI8aZVTyxp3Bvk9Hg8=
 github.com/hashicorp/terraform-plugin-framework v1.7.0 h1:wOULbVmfONnJo9iq7/q+iBOBJul5vRovaYJIu2cY/Pw=
 github.com/hashicorp/terraform-plugin-framework v1.7.0/go.mod h1:jY9Id+3KbZ17OMpulgnWLSfwxNVYSoYBQFTgsx044CI=
+github.com/hashicorp/terraform-plugin-framework-validators v0.12.0 h1:HOjBuMbOEzl7snOdOoUfE2Jgeto6JOjLVQ39Ls2nksc=
+github.com/hashicorp/terraform-plugin-framework-validators v0.12.0/go.mod h1:jfHGE/gzjxYz6XoUwi/aYiiKrJDeutQNUtGQXkaHklg=
 github.com/hashicorp/terraform-plugin-go v0.22.1 h1:iTS7WHNVrn7uhe3cojtvWWn83cm2Z6ryIUDTRO0EV7w=
 github.com/hashicorp/terraform-plugin-go v0.22.1/go.mod h1:qrjnqRghvQ6KnDbB12XeZ4FluclYwptntoWCr9QaXTI=
 github.com/hashicorp/terraform-plugin-log v0.9.0 h1:i7hOA+vdAItN1/7UrfBqBwvYPQ9TFvymaRGZED3FCV0=