doc: add best-practices for terraform dependency locking

meshcloud · Jul 21, 2023 · 5d4177a · 5d4177a
1 parent d01be88
commit 5d4177a
Show file tree

Hide file tree

Showing 3 changed files with 18 additions and 4 deletions.
diff --git a/docs/.vuepress/config.ts b/docs/.vuepress/config.ts
@@ -66,9 +66,8 @@ export const sidebar: SidebarConfig = {
       text: "Guides",
       children: [
         '/guide/README.md',
-        '/guide/bootstrapping.md',
+        '/guide/best-practices.md',
         '/guide/compliance.md',
-        '/guide/best-practices.md'
       ]
     },
   ],

diff --git a/docs/guide/README.md b/docs/guide/README.md
@@ -2,8 +2,8 @@
 
 > Note: this section of the documentation is under constrution
 
-This section contains problem-oriented guides that aim to help you working with Landing Zone Construction Kit.
+This section contains problem-oriented guides that aim to help you working with collie to build landing zones.
 
-- [Bootstrapping Landing Zones](bootstrapping.md) provides an overview of how to boostrap landing zone deployments
+- [Best Practices](best-practices.md) provides an overview of some best practices working with collie and its underlying tools like terraform and terragrunt
 - [Manage Compliance](compliance.md) gives you an overview of the features of the Kit that enable you to manage
 compliance of your landing zones
diff --git a/docs/guide/best-practices.md b/docs/guide/best-practices.md
@@ -73,3 +73,18 @@ Terragrunt offers many advanced features to keep configuration DRY. However, som
 lesser evil. Terragrunt configurations can get "too clever" quickly, especially when they compose from too many
 different dynamic configuration sources. We therefore recommend keeping terragrunt trickery to a minimum and stick to
 basic features like `include` and `dependency` for as long as possible.
+
+### Managing .terraform.lock.hcl files
+
+Terraform uses `.terraform.lock.hcl` files to [lock dependency versions](https://developer.hashicorp.com/terraform/language/files/dependency-lock) of providers and modules. If members of your cloud foundation team run a variety of operating systems and CPU architectures
+managing these locks in a way that members of your team won't see depency locking issues can be [very cumbersome](https://github.com/hashicorp/terraform/issues/29958).
+
+One important trick is to make sure that lock files contain entries for all OS and cpu architectures used in your team.
+This can be accomplished by running `terraform providers lock` across all your platform modules.
+
+```sh
+ collie foundation deploy my-foundation -- providers lock -platform=darwin_amd64 -platform=linux_amd64 -platform=darwin_arm64
+```
+
+Edit the `-platform` commands as appropriate. Don't forget committing the resulting lock file updates back to your repository
+to share with your team.