📖 Update documentation (#76)

Update FAQ, Module and Workspace docs, and add examples.

Co-authored-by: John Houston <jrhouston@users.noreply.github.com>

README.md

@@ -94,6 +94,10 @@ API reference documentation can be found [here](./docs/api-reference.md).
 
 FAQ can be found [here](./docs/faq.md).
 
+### Examples
+
+YAML manifests examples live [here](./docs/examples/README.md).
+
 ## Operator Options
 
 Global options:

api/v1alpha2/module_types.go

@@ -19,7 +19,7 @@ type ModuleSource struct {
 }
 
 // Workspace to execute the module.
-// Either 'ID' or 'Name' must be specified.
+// Only one of the fields `ID` or `Name` is allowed.
 type ModuleWorkspace struct {
 	// Module Workspace ID.
 	//+kubebuilder:validation:Pattern="^ws-[a-zA-Z0-9]+$"

api/v1alpha2/workspace_types.go

@@ -9,6 +9,8 @@ import (
 )
 
 // AgentPool allows Terraform Cloud to communicate with isolated, private, or on-premises infrastructure.
+// Only one of the fields `ID` or `Name` is allowed.
+//
 // More information:
 //   - https://developer.hashicorp.com/terraform/cloud-docs/agents
 type WorkspaceAgentPool struct {
@@ -22,6 +24,8 @@ type WorkspaceAgentPool struct {
 }
 
 // ConsumerWorkspace allows access to the state for specific workspaces within the same organization.
+// Only one of the fields `ID` or `Name` is allowed.
+//
 // More information:
 //   - https://developer.hashicorp.com/terraform/cloud-docs/workspaces/state#remote-state-access-controls
 type ConsumerWorkspace struct {
@@ -50,6 +54,8 @@ type RemoteStateSharing struct {
 
 // RunTrigger allows you to connect this workspace to one or more source workspaces.
 // These connections allow runs to queue automatically in this workspace on successful apply of runs in any of the source workspaces.
+// Only one of the fields `ID` or `Name` is allowed.
+//
 // More information:
 //   - https://developer.hashicorp.com/terraform/cloud-docs/workspaces/settings/run-triggers
 type RunTrigger struct {
@@ -64,6 +70,8 @@ type RunTrigger struct {
 
 // Teams are groups of Terraform Cloud users within an organization.
 // If a user belongs to at least one team in an organization, they are considered a member of that organization.
+// Only one of the fields `ID` or `Name` is allowed.
+//
 // More information:
 //   - https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/teams
 type Team struct {
@@ -187,6 +195,8 @@ type VersionControl struct {
 }
 
 // SSH key used to clone Terraform modules
+// Only one of the fields `ID` or `Name` is allowed.
+//
 // More information:
 //   - https://developer.hashicorp.com/terraform/cloud-docs/workspaces/settings/ssh-keys
 type SSHKey struct {

docs/api-reference.md

@@ -87,7 +87,8 @@ _Appears in:_
 
 
 
-ConsumerWorkspace allows access to the state for specific workspaces within the same organization. More information:   - https://developer.hashicorp.com/terraform/cloud-docs/workspaces/state#remote-state-access-controls
+ConsumerWorkspace allows access to the state for specific workspaces within the same organization. Only one of the fields `ID` or `Name` is allowed. 
+ More information:   - https://developer.hashicorp.com/terraform/cloud-docs/workspaces/state#remote-state-access-controls
 
 _Appears in:_
 - [RemoteStateSharing](#remotestatesharing)
@@ -205,7 +206,7 @@ _Appears in:_
 
 
 
-Workspace to execute the module. Either 'ID' or 'Name' must be specified.
+Workspace to execute the module. Only one of the fields `ID` or `Name` is allowed.
 
 _Appears in:_
 - [ModuleSpec](#modulespec)
@@ -266,7 +267,8 @@ _Appears in:_
 
 
 
-RunTrigger allows you to connect this workspace to one or more source workspaces. These connections allow runs to queue automatically in this workspace on successful apply of runs in any of the source workspaces. More information:   - https://developer.hashicorp.com/terraform/cloud-docs/workspaces/settings/run-triggers
+RunTrigger allows you to connect this workspace to one or more source workspaces. These connections allow runs to queue automatically in this workspace on successful apply of runs in any of the source workspaces. Only one of the fields `ID` or `Name` is allowed. 
+ More information:   - https://developer.hashicorp.com/terraform/cloud-docs/workspaces/settings/run-triggers
 
 _Appears in:_
 - [WorkspaceSpec](#workspacespec)
@@ -281,7 +283,8 @@ _Appears in:_
 
 
 
-SSH key used to clone Terraform modules More information:   - https://developer.hashicorp.com/terraform/cloud-docs/workspaces/settings/ssh-keys
+SSH key used to clone Terraform modules Only one of the fields `ID` or `Name` is allowed. 
+ More information:   - https://developer.hashicorp.com/terraform/cloud-docs/workspaces/settings/ssh-keys
 
 _Appears in:_
 - [WorkspaceSpec](#workspacespec)
@@ -296,7 +299,8 @@ _Appears in:_
 
 
 
-Teams are groups of Terraform Cloud users within an organization. If a user belongs to at least one team in an organization, they are considered a member of that organization. More information:   - https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/teams
+Teams are groups of Terraform Cloud users within an organization. If a user belongs to at least one team in an organization, they are considered a member of that organization. Only one of the fields `ID` or `Name` is allowed. 
+ More information:   - https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/teams
 
 _Appears in:_
 - [TeamAccess](#teamaccess)
@@ -410,7 +414,8 @@ Workspace is the Schema for the workspaces API
 
 
 
-AgentPool allows Terraform Cloud to communicate with isolated, private, or on-premises infrastructure. More information:   - https://developer.hashicorp.com/terraform/cloud-docs/agents
+AgentPool allows Terraform Cloud to communicate with isolated, private, or on-premises infrastructure. Only one of the fields `ID` or `Name` is allowed. 
+ More information:   - https://developer.hashicorp.com/terraform/cloud-docs/agents
 
 _Appears in:_
 - [WorkspaceSpec](#workspacespec)

docs/examples/README.md

@@ -0,0 +1,7 @@
+# Examples
+
+Here you can find different examples of the YAML manifests. They aim to demonstrate the usage of the different features supported by the Operator and do not seek to demonstrate all possible combinations.
+
+All examples must be based on basic examples `*-basic.yaml`.
+
+If you encounter any issues with examples or want to add more, please feel free to open a new issue!

docs/examples/agentPool-basic.yaml

@@ -0,0 +1,17 @@
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: MPL-2.0
+
+---
+apiVersion: app.terraform.io/v1alpha2
+kind: AgentPool
+metadata:
+  name: this
+spec:
+  organization: kubernetes-operator
+  token:
+    secretKeyRef:
+      name: tfc-operator
+      key: token
+  name: agent-pool-demo
+  agentTokens:
+    - name: token

docs/examples/module-basic.yaml

@@ -0,0 +1,22 @@
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: MPL-2.0
+
+---
+apiVersion: app.terraform.io/v1alpha2
+kind: Module
+metadata:
+  name: this
+spec:
+  organization: kubernetes-operator
+  token:
+    secretKeyRef:
+      name: tfc-operator
+      key: token
+  module:
+    source: redeux/terraform-cloud-agent/kubernetes
+    version: 1.0.1
+  workspace:
+    id: ws-NUVHA9feCXzAmPHx
+    # Alternatively, you can use the Workspace name:
+    #
+    # name: workspace-name

docs/examples/workspace-basic.yaml

@@ -0,0 +1,15 @@
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: MPL-2.0
+
+---
+apiVersion: app.terraform.io/v1alpha2
+kind: Workspace
+metadata:
+  name: this
+spec:
+  organization: kubernetes-operator
+  token:
+    secretKeyRef:
+      name: tfc-operator
+      key: token
+  name: kubernetes-operator-demo

docs/examples/workspace-runTriggers.yaml

@@ -0,0 +1,18 @@
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: MPL-2.0
+
+---
+apiVersion: app.terraform.io/v1alpha2
+kind: Workspace
+metadata:
+  name: this
+spec:
+  organization: kubernetes-operator
+  token:
+    secretKeyRef:
+      name: tfc-operator
+      key: token
+  name: kubernetes-operator-demo
+  runTriggers:
+    - id: ws-NUVHA9feCXzAmPHx
+    - name: target-workspace

docs/examples/workspace-terraformVersion.yaml

@@ -0,0 +1,16 @@
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: MPL-2.0
+
+---
+apiVersion: app.terraform.io/v1alpha2
+kind: Workspace
+metadata:
+  name: this
+spec:
+  organization: kubernetes-operator
+  token:
+    secretKeyRef:
+      name: tfc-operator
+      key: token
+  name: kubernetes-operator-demo
+  terraformVersion: 1.3.7

docs/faq.md

@@ -110,6 +110,27 @@
 
   With the default values of `sync-period` (5 minutes) and `*-workers` (1 worker per controller), we recommend managing **100 resources per token**. This number can vary based on previously mentioned factors. This number can be updated later to accommodate changes in the Terraform Cloud API.
 
+- **What can be done to improve performance?**
+
+  The Operator allows you to refer to Terraform Cloud resources by their name or ID. For example, the `Workspace` controller allows you to specify another workspace to use as a [Run Trigger](https://developer.hashicorp.com/terraform/cloud-docs/workspaces/settings/run-triggers).  It accepts a list of workspaces that will be triggered where each item can either be the `ID` or `Name` of the workspace. When you use a name, the Operator does an API call on each reconciliation in order to get the ID of the target Workspace. This makes configurations easier to read, but causes more API calls to be as the operator needs to figure out what the ID of workspace is from the name. 
+
+  One way to improve performance is to use the referred object ID. In this example, by the Workspace ID. In this case, the Operator will use the ID directly without trying to resolve it.
+
+  Here is a short example to demonstrate both options:
+
+  ```yaml
+  apiVersion: app.terraform.io/v1alpha2
+  kind: Workspace
+  metadata:
+  name: this
+  spec:
+    runTriggers:
+      - id: ws-NUVHA9feCXzAmPHx
+      - name: target-workspace
+  ```
+
+  Please refer to the [CRDs](../config/crd/bases) and [API Reference](./api-reference.md) to see if the feature you use supports `ID` or `Name`.
+
 ## Workspace Controller
 
 - **Can a single deployment of the Operator manage the Workspaces of different Organizations?**

docs/module.md

@@ -2,6 +2,8 @@
 
 `Module` controller allows executing arbitrary Terraform Modules code in Terraform Cloud Workspace via Kubernetes Custom Resources.
 
+Please refer to the [CRD](../config/crd/bases/app.terraform.io_modules.yaml) and [API Reference](./api-reference.md#module) to get the full list of available options.
+
 Below is an example of a Module Custom Resource:
 
 ```yaml
@@ -63,4 +65,6 @@ $ kubectl patch module <NAME> \
   --patch '{"spec": {"restartedAt": "'`date -u -Iseconds`'"}}'
 ```
 
-Please refer to the [CRD](../config/crd/bases/app.terraform.io_modules.yaml) to get the full list of available options.
+If you have any questions, please check out the [FAQ](./faq.md#module-controller).
+
+If you encounter any issues with the `AgentPool` controller please refer to the [Troubleshooting](../README.md#troubleshooting).

docs/workspace.md

@@ -2,6 +2,8 @@
 
 `Workspace` controller allows managing Terraform Cloud Workspace via Kubernetes Custom Resources.
 
+Please refer to the [CRD](../config/crd/bases/app.terraform.io_workspaces.yaml) and [API Reference](./api-reference.md#workspace) to get the full list of available options.
+
 Below is an example of a Workspace Custom Resource:
 
 ```yaml
@@ -40,4 +42,6 @@ Once the above CR is applied, the Operator creates a new workspace `workspace-de
 
 Non-sensitive outputs of the workspace runs will be saved in Kubernetes ConfigMaps. Sensitive outputs of the workspace runs will be saved in Kubernetes Secrets. In both cases, the name of the corresponding Kubernetes object will be generated automatically and has the following pattern: `<metadata.name>-outputs`. For the above example, the name of ConfigMap and Secret will be `this-outputs`.
 
-Please refer to the [CRD](../config/crd/bases/app.terraform.io_workspaces.yaml) to get the full list of available options.
+If you have any questions, please check out the [FAQ](./faq.md#workspace-controller).
+
+If you encounter any issues with the `Workspace` controller please refer to the [Troubleshooting](../README.md#troubleshooting).