Chore/docs v1

docs/examples/creating-a-standardised-space-and-project.md

@@ -0,0 +1,9 @@
+---
+page_title: "Creating a Standardised Space and Project"
+subcategory: "Examples"
+---
+
+# Creating a Standardised Space and Project
+
+This example show how to create a standardised space and project that can be used to quickly setup applications used as
+microservices.

templates/guides/4-create-multiple-resources.md.tmpl → docs/guides/create-multiple-resources.md

@@ -1,11 +1,11 @@
 ---
-page_title: "4. Creating Multiple Resources"
+page_title: "Creating Multiple Resources"
 subcategory: "Guides"
 ---
 
-# 4. Creating multiple Octopus Deploy resources
+# Creating multiple Octopus Deploy resources
 
-In step 3, you learned about creating one resource. In this step we will create multiple resources with the same Terraform config file.
+In Creating a Resource guide, you learned about creating one resource. In this guide we will create multiple resources with the same Terraform config file.
 
 The below Terraform configuration will create the following Octopus Deploy resources:
 * Environment

docs/guides/3-create-resource.md → docs/guides/create-resource.md

@@ -1,9 +1,9 @@
 ---
-page_title: "3. Creating a Resource"
+page_title: "Creating a Resource"
 subcategory: "Guides"
 ---
 
-# 3. Creating your first Octopus Deploy resource
+# Creating your first Octopus Deploy resource
 
 ## Provider Setup
 

docs/guides/how-to-find-step-properties.md

@@ -0,0 +1,24 @@
+---
+page_title: "How to Find Step Properties"
+subcategory: "Guides"
+---
+
+# How to Find Step Properties
+
+When defining step properties for a deployment or runbook process it can be challenging to discover the required key and
+values for a step. This guides goal is to help with the discovery of step properties.
+
+To discover properties for a step its best to first define deployment process within the UI including the steps you wish
+to use within the provider. Once the deployment process is defined and the step are configured do the following:
+
+1. Click the ellipsis to the right of the `save` button on the Process Editor page
+1. From the menu select `Download as JSON`
+1. Open the downloaded JSON file in an editor of your choice
+1. Within the JSON you will find a key `Steps`, this is an array of step objects. The objects are in the run order.
+1. Locate the key `Properties` within a step object, this maps to the key/value pairs for the `properties` field on the `process_step` resource in HCL.
+1. Locate the key `Actions` within a step object, this is and array of actions. Every Step object will have at lest one action, the first action is always related to the step object while additional actions are used to define child steps.
+1. Locate the key `Properties` within the first action object of the array, this maps the key/value pairs for the `execution_properties` field on the `process_step` resource in HCL.
+1. The following action objects within the array, if any, will map to the `property` key to the `execution_properties` field on the `process_child_step` resource within HCL.
+
+
+Note that in the future we plan to improve the discoverability of step properties.

templates/guides/2-provider-configuration.md.tmpl → docs/guides/provider-configuration.md

@@ -1,9 +1,9 @@
 ---
-page_title: "2. Octopus Deploy Provider Configuration"
+page_title: "Octopus Deploy Provider Configuration"
 subcategory: "Guides"
 ---
 
-# 2. Octopus Deploy Provider Configuration
+# Octopus Deploy Provider Configuration
 
 ## Example usage
 

docs/guides/1-terraform.md → docs/guides/why-terraform.md

@@ -1,9 +1,9 @@
 ---
-page_title: "1. Why Terraform?"
+page_title: "Why Terraform?"
 subcategory: "Guides"
 ---
 
-# 1. Why Terraform?
+# Why Terraform?
 
 If you're new to Terraform in general, it may be in your best interest to start with some Terraform Getting Started Docs. 
 

docs/resources/aws_openid_connect_account.md

@@ -1,5 +1,4 @@
 ---
-# generated by https://github.com/hashicorp/terraform-plugin-docs
 page_title: "octopusdeploy_aws_openid_connect_account Resource - terraform-provider-octopusdeploy"
 subcategory: ""
 description: |-
@@ -10,7 +9,19 @@ description: |-
 
 This resource manages AWS OIDC accounts in Octopus Deploy.
 
-
+## Example Usage
+
+```terraform
+resource "octopusdeploy_aws_openid_connect_account" "example" {
+  name = "AWS OIDC Account"
+  description = "AWS OIDC Connect Account"
+  role_arn = "Amazon Resource Name"
+  account_test_subject_keys = ["space"]
+  environments = ["environment-123"]
+  tenants = ["tenants-123"]
+  execution_subject_keys = ["space"]
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema

docs/resources/library_variable_set.md

@@ -1,5 +1,4 @@
 ---
-# generated by https://github.com/hashicorp/terraform-plugin-docs
 page_title: "octopusdeploy_library_variable_set Resource - terraform-provider-octopusdeploy"
 subcategory: ""
 description: |-
@@ -10,43 +9,10 @@ description: |-
 
 This resource manages library variable sets in Octopus Deploy.
 
+## Import
 
+Import is supported using the following syntax:
 
-<!-- schema generated by tfplugindocs -->
-## Schema
-
-### Required
-
-- `name` (String) The name of this resource.
-
-### Optional
-
-- `description` (String) The description of this library variable set.
-- `space_id` (String) The space ID associated with this library variable set.
-- `template` (Block List) (see [below for nested schema](#nestedblock--template))
-
-### Read-Only
-
-- `id` (String) The unique ID for this resource.
-- `template_ids` (Map of String)
-- `variable_set_id` (String)
-
-<a id="nestedblock--template"></a>
-### Nested Schema for `template`
-
-Required:
-
-- `name` (String) The name of the variable set by the parameter. The name can contain letters, digits, dashes and periods. Example: `ServerName`
-
-Optional:
-
-- `default_value` (String) A default value for the parameter, if applicable. This can be a hard-coded value or a variable reference.
-- `display_settings` (Map of String) The display settings for the parameter.
-- `help_text` (String) The help presented alongside the parameter input.
-- `label` (String) The label shown beside the parameter when presented in the deployment process. Example: `Server name`.
-
-Read-Only:
-
-- `id` (String) The unique ID for this resource.
-
-
+```shell
+terraform import [options] octopusdeploy_library_variable_set.<name> <library-variable-sets-id>
+```

docs/resources/process_step.md

@@ -21,6 +21,8 @@ This resource also contains a concept that doesn't exist in the Octopus Deploy d
 * `properties` are the inputs to the step itself
 * `execution_properties` are the controls for _how_ the step runs, particularly relevant in parent/child step situations
 
+For more information on how to discover step properties read the *How to Find Step Properties* under the guides section of the documentation.
+
 ## Example Usage
 
 ```terraform

docs/resources/process_templated_child_step.md

@@ -10,7 +10,9 @@ description: |-
 This resource manages a child step of a Runbook or Deployment process which based on existing custom step template
 
 ### Remarks
-This resource exposes only attributes which can be controlled by the consumer of a template. 
+This resource exposes only attributes which can be controlled by the consumer of a template.
+
+For more information on how to discover step properties read the *How to Find Step Properties* under the guides section of the documentation.
 
 ## Example Usage
 

docs/resources/tenant_project.md

@@ -1,5 +1,4 @@
 ---
-# generated by https://github.com/hashicorp/terraform-plugin-docs
 page_title: "octopusdeploy_tenant_project Resource - terraform-provider-octopusdeploy"
 subcategory: ""
 description: |-
@@ -10,7 +9,17 @@ description: |-
 
 
 
+## Example Usage
 
+```terraform
+resource "octopusdeploy_tenant_project" "example" {
+  project_id = "project-123"
+  tenant_id = "tenant-123"
+  environment_ids = [
+    "environment-123"
+  ]
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
@@ -29,4 +38,10 @@ description: |-
 
 - `id` (String) The unique ID for this resource.
 
+## Import
 
+Import is supported using the following syntax:
+
+```shell
+terraform import [options] octopusdeploy_tenant_project.<name> <space-id:tenant-id:project-id>
+```

docs/resources/tenant_project_variable.md

@@ -1,5 +1,4 @@
 ---
-# generated by https://github.com/hashicorp/terraform-plugin-docs
 page_title: "octopusdeploy_tenant_project_variable Resource - terraform-provider-octopusdeploy"
 subcategory: ""
 description: |-
@@ -10,7 +9,17 @@ description: |-
 
 Manages a tenant project variable in Octopus Deploy.
 
+## Example Usage
 
+```terraform
+resource "octopusdeploy_tenant_project_variable" "example" {
+  environment_id = "environment-123"
+  project_id = "project-123"
+  template_id = "template-123"
+  tenant_id = "tenant-123"
+  value = "my-tenant-project-variable-value"
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
@@ -31,4 +40,10 @@ Manages a tenant project variable in Octopus Deploy.
 
 - `id` (String) The unique ID for this resource.
 
+## Import
 
+Import is supported using the following syntax:
+
+```shell
+terraform import [options] octopusdeploy_tanant_project_variable.<name> <tenant-id:project-id:environment-id:template-id>
+```

examples/resources/octopusdeploy_aws_openid_connect_account/resource.tf

@@ -0,0 +1,9 @@
+resource "octopusdeploy_aws_openid_connect_account" "example" {
+  name = "AWS OIDC Account"
+  description = "AWS OIDC Connect Account"
+  role_arn = "Amazon Resource Name"
+  account_test_subject_keys = ["space"]
+  environments = ["environment-123"]
+  tenants = ["tenants-123"]
+  execution_subject_keys = ["space"]
+}

examples/resources/octopusdeploy_library_variable_set/import.sh

@@ -0,0 +1 @@
+terraform import [options] octopusdeploy_library_variable_set.<name> <library-variable-sets-id>

examples/resources/octopusdeploy_tenant_project/import.sh

@@ -0,0 +1 @@
+terraform import [options] octopusdeploy_tenant_project.<name> <space-id:tenant-id:project-id>

examples/resources/octopusdeploy_tenant_project/resource.tf

@@ -0,0 +1,7 @@
+resource "octopusdeploy_tenant_project" "example" {
+  project_id = "project-123"
+  tenant_id = "tenant-123"
+  environment_ids = [
+    "environment-123"
+  ]
+}

examples/resources/octopusdeploy_tenant_project_variable/import.sh

@@ -0,0 +1 @@
+terraform import [options] octopusdeploy_tanant_project_variable.<name> <tenant-id:project-id:environment-id:template-id>

examples/resources/octopusdeploy_tenant_project_variable/resource.tf

@@ -0,0 +1,7 @@
+resource "octopusdeploy_tenant_project_variable" "example" {
+  environment_id = "environment-123"
+  project_id = "project-123"
+  template_id = "template-123"
+  tenant_id = "tenant-123"
+  value = "my-tenant-project-variable-value"
+}

templates/examples/creating-a-standardised-space-and-project.md.tmpl

@@ -0,0 +1,9 @@
+---
+page_title: "Creating a Standardised Space and Project"
+subcategory: "Examples"
+---
+
+# Creating a Standardised Space and Project
+
+This example show how to create a standardised space and project that can be used to quickly setup applications used as
+microservices.

docs/guides/4-create-multiple-resources.md → templates/guides/create-multiple-resources.md.tmpl

@@ -1,11 +1,11 @@
 ---
-page_title: "4. Creating Multiple Resources"
+page_title: "Creating Multiple Resources"
 subcategory: "Guides"
 ---
 
-# 4. Creating multiple Octopus Deploy resources
+# Creating multiple Octopus Deploy resources
 
-In step 3, you learned about creating one resource. In this step we will create multiple resources with the same Terraform config file.
+In Creating a Resource guide, you learned about creating one resource. In this guide we will create multiple resources with the same Terraform config file.
 
 The below Terraform configuration will create the following Octopus Deploy resources:
 * Environment

templates/guides/3-create-resource.md.tmpl → templates/guides/create-resource.md.tmpl

@@ -1,9 +1,9 @@
 ---
-page_title: "3. Creating a Resource"
+page_title: "Creating a Resource"
 subcategory: "Guides"
 ---
 
-# 3. Creating your first Octopus Deploy resource
+# Creating your first Octopus Deploy resource
 
 ## Provider Setup
 

templates/guides/how-to-find-step-properties.md.tmpl

@@ -0,0 +1,24 @@
+---
+page_title: "How to Find Step Properties"
+subcategory: "Guides"
+---
+
+# How to Find Step Properties
+
+When defining step properties for a deployment or runbook process it can be challenging to discover the required key and
+values for a step. This guides goal is to help with the discovery of step properties.
+
+To discover properties for a step its best to first define deployment process within the UI including the steps you wish
+to use within the provider. Once the deployment process is defined and the step are configured do the following:
+
+1. Click the ellipsis to the right of the `save` button on the Process Editor page
+1. From the menu select `Download as JSON`
+1. Open the downloaded JSON file in an editor of your choice
+1. Within the JSON you will find a key `Steps`, this is an array of step objects. The objects are in the run order.
+1. Locate the key `Properties` within a step object, this maps to the key/value pairs for the `properties` field on the `process_step` resource in HCL.
+1. Locate the key `Actions` within a step object, this is and array of actions. Every Step object will have at lest one action, the first action is always related to the step object while additional actions are used to define child steps.
+1. Locate the key `Properties` within the first action object of the array, this maps the key/value pairs for the `execution_properties` field on the `process_step` resource in HCL.
+1. The following action objects within the array, if any, will map to the `property` key to the `execution_properties` field on the `process_child_step` resource within HCL.
+
+
+Note that in the future we plan to improve the discoverability of step properties.

docs/guides/2-provider-configuration.md → templates/guides/provider-configuration.md.tmpl

@@ -1,9 +1,9 @@
 ---
-page_title: "2. Octopus Deploy Provider Configuration"
+page_title: "Octopus Deploy Provider Configuration"
 subcategory: "Guides"
 ---
 
-# 2. Octopus Deploy Provider Configuration
+# Octopus Deploy Provider Configuration
 
 ## Example usage
 

templates/guides/1-terraform.md.tmpl → templates/guides/why-terraform.md.tmpl

@@ -1,9 +1,9 @@
 ---
-page_title: "1. Why Terraform?"
+page_title: "Why Terraform?"
 subcategory: "Guides"
 ---
 
-# 1. Why Terraform?
+# Why Terraform?
 
 If you're new to Terraform in general, it may be in your best interest to start with some Terraform Getting Started Docs.