diff --git a/README.md b/README.md index 87186d06..fa604b99 100644 --- a/README.md +++ b/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: diff --git a/api/v1alpha2/module_types.go b/api/v1alpha2/module_types.go index 98b79321..d653f5fe 100644 --- a/api/v1alpha2/module_types.go +++ b/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]+$" diff --git a/api/v1alpha2/workspace_types.go b/api/v1alpha2/workspace_types.go index 8d1619e8..643227dd 100644 --- a/api/v1alpha2/workspace_types.go +++ b/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 { diff --git a/docs/api-reference.md b/docs/api-reference.md index 959371df..9870ee14 100644 --- a/docs/api-reference.md +++ b/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) diff --git a/docs/examples/README.md b/docs/examples/README.md new file mode 100644 index 00000000..d7858120 --- /dev/null +++ b/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! diff --git a/docs/examples/agentPool-basic.yaml b/docs/examples/agentPool-basic.yaml new file mode 100644 index 00000000..15c17d95 --- /dev/null +++ b/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 diff --git a/docs/examples/module-basic.yaml b/docs/examples/module-basic.yaml new file mode 100644 index 00000000..89af74b7 --- /dev/null +++ b/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 diff --git a/docs/examples/workspace-basic.yaml b/docs/examples/workspace-basic.yaml new file mode 100644 index 00000000..b7787cb0 --- /dev/null +++ b/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 diff --git a/docs/examples/workspace-runTriggers.yaml b/docs/examples/workspace-runTriggers.yaml new file mode 100644 index 00000000..7bde8dab --- /dev/null +++ b/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 diff --git a/docs/examples/workspace-terraformVersion.yaml b/docs/examples/workspace-terraformVersion.yaml new file mode 100644 index 00000000..b3cab628 --- /dev/null +++ b/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 diff --git a/docs/faq.md b/docs/faq.md index 71f7978d..71bfc9f2 100644 --- a/docs/faq.md +++ b/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 referring to a TFC object by the ID or name. For example, the `Workspace` controller supports the Run Triggers option. It accepts a list of Workspaces that will be triggered. An item can be referred to either by `ID` or `Name`. When you use a name, the Operator does an API call on each reconciliation in order to get the ID of the target Workspace. It makes it more dynamic but causes extra API calls. + + 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?** diff --git a/docs/module.md b/docs/module.md index 0d8ff7cb..d9b78535 100644 --- a/docs/module.md +++ b/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 \ --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) to see if you can find answers there. + +If you encounter any issues with the `AgentPool` controller please refer to the [Troubleshooting](../README.md#troubleshooting). diff --git a/docs/workspace.md b/docs/workspace.md index c8808a2f..c8c30494 100644 --- a/docs/workspace.md +++ b/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: `-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) to see if you can find answers there. + +If you encounter any issues with the `Workspace` controller please refer to the [Troubleshooting](../README.md#troubleshooting).