From 945bff8d8f67e781f5786eaca6d01a60da3cdc31 Mon Sep 17 00:00:00 2001
From: Igor Rodionov <goruha@gmail.com>
Date: Fri, 29 Nov 2024 21:06:36 +0300
Subject: [PATCH] Update README.yaml

---
 README.yaml | 105 +++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 103 insertions(+), 2 deletions(-)

diff --git a/README.yaml b/README.yaml
index 378de2f..2b7d1bb 100644
--- a/README.yaml
+++ b/README.yaml
@@ -52,13 +52,26 @@ references:
 usage: |-
   ### Config
 
+  > [!IMPORTANT]
+  > **Please note!** This GitHub Action only works with `atmos >= 1.99.0`.
+  > If you are using `atmos >= 1.63.0, < 1.99.0` please use `v2` version of this action.  
+  > If you are using `atmos < 1.63.0` please use `v1` version of this action.
+
   The action expects the atmos configuration file `atmos.yaml` to be present in the repository.
+  
+  The action supports AWS and Azure to store Terraform plan files. 
+  You can read more about plan storage in the [cloudposse/github-action-terraform-plan-storage](https://github.com/cloudposse/github-action-terraform-plan-storage?tab=readme-ov-file#aws-default) documentation. 
+  Depends of cloud provider the following fields should be set in the `atmos.yaml`:
+  
+  #### AWS
+  
   The config should have the following structure:
   
   ```yaml
   integrations:
     github:
       gitops:
+        opentofu-version: 1.7.3  
         terraform-version: 1.5.2
         infracost-enabled: false
         artifact-storage:
@@ -68,14 +81,92 @@ usage: |-
           role: arn:aws:iam::xxxxxxxxxxxx:role/cptest-core-ue2-auto-gitops-gha
         role:
           plan: arn:aws:iam::yyyyyyyyyyyy:role/cptest-core-gbl-identity-gitops
+          # Set `apply` empty if you don't want to assume IAM role before terraform apply
           apply: arn:aws:iam::yyyyyyyyyyyy:role/cptest-core-gbl-identity-gitops
         matrix:
           sort-by: .stack_slug
           group-by: .stack_slug | split("-") | [.[0], .[2]] | join("-")
   ```
+
+  #### Azure
+  
+  The config should have the following structure:
+  
+  ```yaml
+  integrations:
+    github:
+      gitops:
+        opentofu-version: 1.7.3  
+        terraform-version: 1.5.2
+        infracost-enabled: false
+        artifact-storage:
+          plan-repository-type: azureblob
+          blob-account-name: tfplans
+          blob-container-name: plans
+          metadata-repository-type: cosmos
+          cosmos-container-name: terraform-plan-storage
+          cosmos-database-name: terraform-plan-storage
+          cosmos-endpoint: "https://my-cosmo-account.documents.azure.com:443/"
+        # We remove the `role` section as it is AWS specific
+        matrix:
+          sort-by: .stack_slug
+          group-by: .stack_slug | split("-") | [.[0], .[2]] | join("-")
+  ```
+
+  ### Stack level configuration
+
+  > [!IMPORTANT]
+  > Wherever it is possible to specify `integration.github.gitops` on stack level 
+  > it is required to define default values in `atmos.yaml`
+
+  It is possible to override integration settings on a stack level by defining `settings.integrations`.
+
+  ```yaml
+  components:
+    terraform:
+      foobar:
+        settings:
+          integrations:
+            github:
+              gitops:
+                artifact-storage:
+                  bucket: cptest-plat-ue2-auto-gitops
+                  table: cptest-plat-ue2-auto-gitops-plan-storage
+                  role: arn:aws:iam::xxxxxxxxxxxx:role/cptest-plat-ue2-auto-gitops-gha
+                role:
+                  # Set `plan` empty if you don't want to assume IAM role before terraform plan  
+                  plan: arn:aws:iam::yyyyyyyyyyyy:role/cptest-plat-gbl-identity-gitops
+                  apply: arn:aws:iam::yyyyyyyyyyyy:role/cptest-plat-gbl-identity-gitops
+  ```    
+
+  ### Support OpenTofu
+  
+  This action supports [OpenTofu](https://opentofu.org/).
   
   > [!IMPORTANT]
-  > **Please note!** This GitHub Action only works with `atmos >= 1.63.0`. If you are using `atmos < 1.63.0` please use `v1` version of this action.    
+  > **Please note!** OpenTofu supported by Atmos `>= 1.73.0`.
+  > For details [read](https://atmos.tools/core-concepts/projects/configuration/opentofu/)
+  
+  To enable OpenTofu add the following settings to `atmos.yaml`
+    * Set the `opentofu-version` in the `atmos.yaml` to the desired version
+    * Set `components.terraform.command` to `tofu`
+  
+  #### Example
+  
+  ```yaml
+  
+  components:
+    terraform:
+      command: tofu
+  
+  ...
+  
+  integrations:
+    github:
+      gitops:
+        opentofu-version: 1.7.3
+        ...
+  ```  
 
   ### Workflow example
 
@@ -124,8 +215,18 @@ usage: |-
             action: discard
             atmos-gitops-config-path: ./.github/config/atmos-gitops.yaml    
   ```
+
+  ### Migrating from `v2` to `v3`
   
-  
+  The notable changes in `v3` are:
+
+  - `v3` works only with `atmos >= 1.99.0`
+  - `v3` use `cloudposse/github-action-atmos-terraform-apply@v3`
+  - `v3` supports stack level integration gitops settings 
+  - `v3` allow to skip internal checkout with `skip-checkout` input
+
+  The only required migration step is updating atmos version to `>= 1.99.0`
+    
   ### Migrating from `v1` to `v2`
   
   The notable changes in `v2` are: