Add migration guide from terraform CI/CD templates

.gitlab/README.md.template

@@ -23,6 +23,10 @@ Read more:
 **Note**: Please make sure to use a released version of this CI/CD component.
 You find all releases on the [Releases Overview Page](https://gitlab.com/components/opentofu/-/releases).
 
+♻️ **Migrating from the Terraform CI/CD templates?** Check **[this](#migrating-from-the-terraform-cicd-templates)** out.
+
+[[_TOC_]]
+
 ## Usage
 
 ```yaml
@@ -69,6 +73,26 @@ include:
 stages: [validate, build, deploy, cleanup]
 ```
 
+Or import all jobs as hidden templates ready to be extended:
+
+```yaml
+include:
+  - component: gitlab.com/components/opentofu/job-templates@<VERSION>
+    inputs:
+      # The version must currently be specified explicitly as an input,
+      # to find the correctly associated images. # This can be removed
+      # once https://gitlab.com/gitlab-org/gitlab/-/issues/438275 is solved.
+      version: <VERSION>
+      opentofu_version: <OPENTOFU_VERSION>
+
+stages: [...]
+
+fmt:
+  extends: [.opentofu:fmt]
+
+...
+```
+
 ### Opinionated Templates
 
 This component repository also provides some templates that may often be used, 
@@ -195,6 +219,26 @@ include:
 This example assumes your GitLab instance is hosted on `gitlab.example.com` and this component
 project is mirrored in the `components/opentofu` project.
 
+## Migrating from the Terraform CI/CD templates
+
+When migrating from the GitLab Terraform CI/CD templates you can use the following migration rules:
+
+- Used `Terraform.gitlab-ci.yml` -> Migrate to `validate-plan-apply`.
+- Used `Terraform/Base.gitlab-ci.yml` -> Migrate to `job-templates`.
+    - Migrate the `.terraform:` job prefix to `.opentofu:`.
+- Used the `kics-iac-sast` job -> Additionally include the `Jobs/SAST-IaC.latest.gitlab-ci.yml` template.
+- Migrate the following job names:
+    - `build` -> `plan`
+    - `deploy` -> `apply`
+- Migrate the `TF_ROOT` variable to the `root_dir` input.
+    - Although the `TF_ROOT` variable is still used and maybe overwritten after the import on individual jobs.
+- Migrate the `TF_STATE_NAME` variable to the `state_name` input.
+    - Although the `TF_STATE_NAME` variable is still used and maybe overwritten after the import on individual jobs.
+- Migrate the `TF_AUTO_DEPLOY` variable to the `auto_apply` input.
+
+The same rules apply for the `latest` templates.
+We also recommend to check out the [Usage](#Usage) section for more details about the available templates and inputs.
+
 ## Contributing
 
 See the [CONTRIBUTING.md](CONTRIBUTING.md) guide.

README.md

@@ -25,6 +25,10 @@ Read more:
 **Note**: Please make sure to use a released version of this CI/CD component.
 You find all releases on the [Releases Overview Page](https://gitlab.com/components/opentofu/-/releases).
 
+♻️ **Migrating from the Terraform CI/CD templates?** Check **[this](#migrating-from-the-terraform-cicd-templates)** out.
+
+[[_TOC_]]
+
 ## Usage
 
 ```yaml
@@ -71,6 +75,26 @@ include:
 stages: [validate, build, deploy, cleanup]
 ```
 
+Or import all jobs as hidden templates ready to be extended:
+
+```yaml
+include:
+  - component: gitlab.com/components/opentofu/job-templates@<VERSION>
+    inputs:
+      # The version must currently be specified explicitly as an input,
+      # to find the correctly associated images. # This can be removed
+      # once https://gitlab.com/gitlab-org/gitlab/-/issues/438275 is solved.
+      version: <VERSION>
+      opentofu_version: <OPENTOFU_VERSION>
+
+stages: [...]
+
+fmt:
+  extends: [.opentofu:fmt]
+
+...
+```
+
 ### Opinionated Templates
 
 This component repository also provides some templates that may often be used, 
@@ -214,6 +238,26 @@ include:
 This example assumes your GitLab instance is hosted on `gitlab.example.com` and this component
 project is mirrored in the `components/opentofu` project.
 
+## Migrating from the Terraform CI/CD templates
+
+When migrating from the GitLab Terraform CI/CD templates you can use the following migration rules:
+
+- Used `Terraform.gitlab-ci.yml` -> Migrate to `validate-plan-apply`.
+- Used `Terraform/Base.gitlab-ci.yml` -> Migrate to `job-templates`.
+    - Migrate the `.terraform:` job prefix to `.opentofu:`.
+- Used the `kics-iac-sast` job -> Additionally include the `Jobs/SAST-IaC.latest.gitlab-ci.yml` template.
+- Migrate the following job names:
+    - `build` -> `plan`
+    - `deploy` -> `apply`
+- Migrate the `TF_ROOT` variable to the `root_dir` input.
+    - Although the `TF_ROOT` variable is still used and maybe overwritten after the import on individual jobs.
+- Migrate the `TF_STATE_NAME` variable to the `state_name` input.
+    - Although the `TF_STATE_NAME` variable is still used and maybe overwritten after the import on individual jobs.
+- Migrate the `TF_AUTO_DEPLOY` variable to the `auto_apply` input.
+
+The same rules apply for the `latest` templates.
+We also recommend to check out the [Usage](#Usage) section for more details about the available templates and inputs.
+
 ## Contributing
 
 See the [CONTRIBUTING.md](CONTRIBUTING.md) guide.