trussworks · clint-truss · Nov 5, 2025 · Nov 6, 2025 · Nov 6, 2025 · Nov 6, 2025
diff --git a/.markdownlintrc b/.markdownlintrc
@@ -7,9 +7,11 @@
   "MD014": false,
   "MD025": false,
   "MD033": false,
+  "MD034": false,
   "MD040": false,
   "MD041": false,
   "MD042": false,
   "MD046": false,
-  "MD051": false
+  "MD051": false,
+  "MD059": false
 }
diff --git a/.node-version b/.node-version
@@ -1 +1 @@
-18.19.1
+22.21.0
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -1,7 +1,7 @@
 ---
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.4.0
+    rev: v6.0.0
     hooks:
       - id: check-merge-conflict
       - id: check-yaml
@@ -10,24 +10,19 @@ repos:
       - id: trailing-whitespace
 
   - repo: https://github.com/igorshubovych/markdownlint-cli
-    rev: v0.33.0
+    rev: v0.45.0
     hooks:
       - id: markdownlint
 
   - repo: https://github.com/executablebooks/mdformat
-    rev: 0.7.16
+    rev: 0.7.22 # we can't adopt 1.0.0 because the dependencies don't support it yet
     hooks:
       - id: mdformat
         additional_dependencies:
           - mdformat-gfm
           - mdformat-toc
           - mdformat-frontmatter
 
-  - repo: https://github.com/trussworks/pre-commit-hooks
-    rev: v1.1.1
-    hooks:
-      - id: circleci-validate
-
   - repo: local
     hooks:
       - id: no-mdformat-toc

diff --git a/docs/developing/code-reviews/README.md b/docs/developing/code-reviews/README.md
@@ -7,7 +7,7 @@ gaining valuable feedback from peers, ensuring that quality standards are upheld
 throughout a project, and defects are caught as early as possible.
 
 We recognize code reviews can be a vulnerable exercise and should be approached
-with care and deliberate intention.  We've collected some of the best practices
+with care and deliberate intention. We've collected some of the best practices
 for projects to systematize the code review process and lay out expectations for
 the creator of the pull request as well as the role of the reviewer.
 

diff --git a/docs/developing/command-line-tools/docker.md b/docs/developing/command-line-tools/docker.md
@@ -3,7 +3,7 @@
 ## Overview
 
 Docker is useful because it allows you to both package and run
-software with all its dependencies and configuration in isolation.  It
+software with all its dependencies and configuration in isolation. It
 also allows you (in theory) to have the same environment in
 development as in CI and production.
 
@@ -18,9 +18,9 @@ brew cask install docker
 ### Configuration of Shared Folders
 
 Anecdata suggests that removing some of the default shared folders can
-decrease CPU usage.  Usually you only need to share volumes under your
-home directory.  Open the docker for mac preferences, then select
-"File Sharing" and then remove `/Volumes` and `/private`.  You may
+decrease CPU usage. Usually you only need to share volumes under your
+home directory. Open the docker for mac preferences, then select
+"File Sharing" and then remove `/Volumes` and `/private`. You may
 also find improvements removing `/Users` and replacing it with
 `/Users/YOUR_USERNAME_GOES_HERE`.
 
@@ -36,13 +36,13 @@ Storage Driver: overlay2
 
 If you don't see overlay2, upgrading to the latest version will add
 that support, but you would need to recreate all of your docker data
-to utilize it.  The `Reset` bomb should do it.
+to utilize it. The `Reset` bomb should do it.
 
 ### Configuration of Disk Image
 
 If you've been running Docker for Mac for some time, make sure you are
-using the `raw` disk image format and not `qcow2`.  Open Docker for
-Mac preferences and select `Disk`.  Make sure the image ends with
+using the `raw` disk image format and not `qcow2`. Open Docker for
+Mac preferences and select `Disk`. Make sure the image ends with
 `Docker.raw`.
 
 ### Configuration of Resources
@@ -59,7 +59,7 @@ by the docker developers.
 ## Volume Mount Performance
 
 Synchronizing the data between the host (your Mac) and the container
-can be resource intensive and/or slow.  Read about the [performance
+can be resource intensive and/or slow. Read about the [performance
 tuning options](https://docs.docker.com/docker-for-mac/osxfs-caching/)
 to see if they might apply to the conditions in your project.
 

diff --git a/docs/developing/eid/README.md b/docs/developing/eid/README.md
@@ -38,14 +38,14 @@ List of editors that Truss engineers use (sorted alphabetically):
 
 ##### Plugins
 
-- [vim-ale](https://github.com:w0rp/ale) - Asynchronous code linter
+- [vim-ale](https://github.com/w0rp/ale) - Asynchronous code linter
 - [editorconfig](https://github.com/editorconfig/editorconfig-vim)
-- [vim-fugitive](https://github.com:tpope/vim-fugitive) - A Git wrapper so awesome, it should be illegal
-- [vim-go](https://github:fatih/vim-go) - golang development plugin for vim
+- [vim-fugitive](https://github.com/tpope/vim-fugitive) - A Git wrapper so awesome, it should be illegal
+- [vim-go](https://github.com/fatih/vim-go) - golang development plugin for vim
 - [vim-javascript](https://github.com/pangloss/vim-javascript)
-- [vim-plug](https://github.com:junegunn/vim-plug) - Minimalist plugin manager
-- [vim-prettier](https://github.com:prettier/vim-prettier)
-- [Recover](https://github.com:chrisbra/Recover.vim) - Displays a diff before recovering a swap file
+- [vim-plug](https://github.com/junegunn/vim-plug) - Minimalist plugin manager
+- [vim-prettier](https://github.com/prettier/vim-prettier)
+- [Recover](https://github.com/chrisbra/Recover.vim) - Displays a diff before recovering a swap file
 
 #### VS Code
 

diff --git a/docs/developing/growth/README.md b/docs/developing/growth/README.md
@@ -13,7 +13,7 @@ speeding up tests) and the client getting the benefit of learning that
 happened elsewhere. Allowing time for growth ensures consistent, high
 quality work which benefits everyone.
 
-Mentoring is an important part of growth.  Truss has [shared some
+Mentoring is an important part of growth. Truss has [shared some
 techniques for
 mentoring](https://truss.works/blog/2016/8/12/theres-a-method-to-the-mentoring-advice-from-a-teacher-turned-developer).
 
@@ -23,6 +23,6 @@ restrict exploration and "just get the ticket done", but that should
 happen infrequently.
 
 If someone is interested in a topic that is not related to their
-client work, a separate plan will need to be made.  That might involve
+client work, a separate plan will need to be made. That might involve
 changing client teams, changing client projects, or joining Truss
 Reserve.
diff --git a/docs/developing/vcs/tools.md b/docs/developing/vcs/tools.md
@@ -48,7 +48,7 @@ for merge conflicts or mistakenly adding secret keys in our code. See
 pre-commit config file from one of our projects.
 
 Since git does not distribute hooks when a repository is cloned, you will
-have to install pre-commit in each cloned repo manually using `pre-commit install --install-hooks` or pre-commit will not run in that repo.  To assist
+have to install pre-commit in each cloned repo manually using `pre-commit install --install-hooks` or pre-commit will not run in that repo. To assist
 with automating this step, pre-commit has a [feature] to exploit the
 [template directory] setting in git:
 

diff --git a/docs/incident-response/on-call.md b/docs/incident-response/on-call.md
@@ -87,7 +87,7 @@ you are expected to fulfill.
   have this covered.
 - If you know you will be away for an extended period during an on-call
   shift, it is *your* responsibility to find someone to cover your shift.
-  If you are unable to, talk to your lead and see if they can help.  If
+  If you are unable to, talk to your lead and see if they can help. If
   you will be gone for more than a day or two, it may be easiest to swap
   the entire shift with someone. PagerDuty allows you to schedule these
   with [overrides](https://community.pagerduty.com/t/creating-a-schedule-override/850).

diff --git a/docs/incident-response/security-incidents.md b/docs/incident-response/security-incidents.md
@@ -10,4 +10,4 @@ to navigate. This document will outline how to approach security
 incidents in general; individual projects will likely have additional
 reporting requirements based on client needs.
 
-\[This is a stub and needs to be expanded.\]
+[This is a stub and needs to be expanded.]
diff --git a/docs/infrasec/adrs/0002-pinning-terraform-version.md b/docs/infrasec/adrs/0002-pinning-terraform-version.md
@@ -0,0 +1,54 @@
+# Guidance for Pinning Terraform Versions
+
+## Context and Problem Statement
+
+On projects, we've both inherited infrastructure as code and we've created it greenfield. In both cases, we have at times failed to pin terraform versions which led to having different versions across different terraform roots. This makes development harder. Additionally, once we've standardized and pinned to a version, when do we revisit that and update it? Based on our practical experience, this ADR seeks to offer that guideance.
+
+## Decision Drivers
+
+- Not pinning versions leads to confusion and difficulty working across a codebase
+- Having TF versions get too out of date can make it harder to upgrade in the future
+- Having versions get very out of date might make it difficult to stay abreast of providers
+
+## Considered Options
+
+- Do Nothing - All projects figure it out
+- Pin, 5 Versions - Establish pinning and keep to no more than 5 minor versions behind
+- Pin, 10 Versions - Establish pinning and keep to 10 minor versions behind
+
+## Decision Outcome
+
+Chosen option: "Pin, 5 Versions", because it does a good job of keeping us up to date but not chasing the bleeding edge of TF versions. For context, as of this writing, the current major release of Terraform is 1.13, released in August 2025. My current project is on 1.8.5, which is five versions back and was released in June of 2024. Using this example, five versions back gives us about a year on a version, which seems about the right cadence for making these kinds of "technical debt" fixes on a codebase.
+
+### Consequences - Pros and Cons
+
+- Good, because it ensures we have consistency of TF version across codebases
+- Good, because it ensures our versions don't get too old
+- Good, because we aren't changing versions too frequently
+- Good, because we have a standard that projects can fall back on instead of re-inventing the wheel
+- Bad, because at some point we do have to do the upgrade in order to stay current
+
+## Validation
+
+This ADR exists to provide guidance for project teams, and is not meant to force compliance. What we want to do is give guidelines for best practices so each project isn't starting over from scratch, and so that when practitioners change from project to project, they have consistency in how the projects operate. This shortens their onboarding time and helps them understand the "state of play" on their new project.
+
+## Pros and Cons of the Other Options
+
+### Do Nothing
+
+We could do nothing and let every project team continue to figure this out for themselves.
+
+- Bad, because we do not have consistency across projects
+- Bad, because we have no standing for project teams when they need to argue for technical debt prioritization. i.e. Customers rarely see value in technical debt updates, yet they are necessary.
+- Bad, because we can wind up in situations where teams go so fast they have wildly different versions across a codebase and it can slow down development (yes, this has happened)
+
+### Pin Version, 10 versions back
+
+We could pin versions and go much farther back so that we are not performing technical debt fixes as often. Pinning 10 vesions back would mean we'd accept TF versions 1.13 - 1.03. 1.03 was released in September 2022, nearly three years ago.
+
+- Good, because we establish guidance for teams and standardize across projects
+- Good, because we aren't changing versions frequently *at all*
+- Good, because we would have consistency across a codebase
+- Bad, because the version could get very old and very unsupported in that length of time
+- Bad, because Terraform is making large changes between versions and could strand the code on an older AWS provider version. For example, AWS 5.x provider can be used from TF 1.0+. AWS 6.0 provider's minimum TF version is 1.5.7.
+- Bad, because the number of changes in three years on a software project is pretty extensive, and could result in a difficult upgrade effort. Terraform has done this in the past.
diff --git a/docs/infrasec/alert-providers.md b/docs/infrasec/alert-providers.md
@@ -89,6 +89,6 @@ it's merited).
 | API                        | Yes ([Documentation](https://docs.opsgenie.com/docs/api-overview))            | Yes ([Documentation](https://v2.developer.pagerduty.com/))              | Yes ([Documentation](https://help.victorops.com/knowledge-base/rest-endpoint-integration-guide/)) |
 | Cloudwatch Integration     | Yes                                                                           | Yes                                                                     | Yes                                                                                               |
 | Slack Integration          | Yes                                                                           | Yes                                                                     | Yes                                                                                               |
-| Other Notable Integrations | CircleCI,  Jira, New Relic, StatusPage                                        | Jira, New Relic, Statuspage                                             | Jira, New Relic, Statuspage                                                                       |
+| Other Notable Integrations | CircleCI, Jira, New Relic, StatusPage                                         | Jira, New Relic, Statuspage                                             | Jira, New Relic, Statuspage                                                                       |
 | Data Retention             | 1 year (unlimited at $29)                                                     | Unlimited                                                               | Not listed (but unlimited noted at $49)                                                           |
 | Terraform Provider         | No ([abandoned](https://www.terraform.io/docs/providers/opsgenie/index.html)) | [Yes](https://www.terraform.io/docs/providers/pagerduty/index.html)     | No official provider, some limited attempts                                                       |
diff --git a/docs/infrasec/ansible/ansible-primer.md b/docs/infrasec/ansible/ansible-primer.md
@@ -5,14 +5,14 @@ remote-execution tool originally designed to orchestrate a wider environment, it
 with things like Packer, which is where you are most likely to see it in a Truss environment.
 
 This primer is not intended to replace the official documentation for Ansible, which can be found at
-<https://docs.ansible.com/ansible/latest/index.html>. It is only intended to provide a high-level overview and give you
+[https://docs.ansible.com/ansible/latest/index.html](https://docs.ansible.com/ansible/latest/index.html). It is only intended to provide a high-level overview and give you
 an idea where to find more detailed resources.
 
 ## Setting up your environment
 
 When working with Ansible, you’ll probably want to set up a virtual environment so that you can install ansible and any
 other Python modules necessary without contaminating your system Python installation. If you’ve never done this before,
-this tutorial should help: <https://www.pythonforbeginners.com/basics/how-to-use-python-virtualenv/>. If you're an
+this tutorial should help: [https://www.pythonforbeginners.com/basics/how-to-use-python-virtualenv/](https://www.pythonforbeginners.com/basics/how-to-use-python-virtualenv/). If you're an
 experienced Python programmer and want to use `pipenv` or another alternative, that's perfectly fine too. It is
 recommended that you use Python 3 as your Python binary.
 

diff --git a/docs/infrasec/ansible/molecule-primer.md b/docs/infrasec/ansible/molecule-primer.md
@@ -7,13 +7,13 @@ experiences and resources you can use when adding testing to your own Ansible ro
 
 These resources will likely come in handy when trying to get Molecule up and running for yourself:
 
-- Molecule Official Docs: <https://molecule.readthedocs.io/en/latest/>
+- Molecule Official Docs: [https://molecule.readthedocs.io/en/latest/](https://molecule.readthedocs.io/en/latest/)
 - Testing Your Ansible Roles with Molecule (Jeff Geerling):
-  <https://www.jeffgeerling.com/blog/2018/testing-your-ansible-roles-molecule>
+  [https://www.jeffgeerling.com/blog/2018/testing-your-ansible-roles-molecule](https://www.jeffgeerling.com/blog/2018/testing-your-ansible-roles-molecule)
 - Test-driven Infrastructure Development with Ansible and Molecule (Jonas Hecht):
-  <https://blog.codecentric.de/en/2018/12/test-driven-infrastructure-ansible-molecule/>
+  [https://blog.codecentric.de/en/2018/12/test-driven-infrastructure-ansible-molecule/](https://blog.codecentric.de/en/2018/12/test-driven-infrastructure-ansible-molecule/)
 - Continuous Cloud Infrastructure With Ansible, Molecule, and TravisCI on AWS (Jonas Hecht):
-  <https://blog.codecentric.de/en/2019/01/ansible-molecule-travisci-aws/>
+  [https://blog.codecentric.de/en/2019/01/ansible-molecule-travisci-aws/](https://blog.codecentric.de/en/2019/01/ansible-molecule-travisci-aws/)
 
 ## Setup
 
@@ -22,8 +22,8 @@ anyway. Using Python 3 as the Python binary is also highly recommended. In addit
 will need these Python modules as well:
 
 - molecule
-- molecule\[docker\] - For testing with docker containers (the default)
-- molecule\[ec2\] - For testing on ec2 instances
+- molecule[docker] - For testing with docker containers (the default)
+- molecule[ec2] - For testing on ec2 instances
 - docker-py
 - boto
 
@@ -46,7 +46,7 @@ for instance, and one with EC2). These commands both take a number of command li
 you’ll probably use is `--driver-name`: This tells molecule which driver to use for the scenario it is creating; by
 default this is docker, but this is where you would put ec2 or vagrant or whatever else if you wanted to test it another
 way. See the Molecule docs here for more information:
-<https://molecule.readthedocs.io/en/latest/configuration.html#driver>.
+[https://molecule.readthedocs.io/en/latest/configuration.html#driver](https://molecule.readthedocs.io/en/latest/configuration.html#driver).
 
 ## Configuration
 
@@ -56,7 +56,7 @@ specify the different components you want to use like driver, linter, verifier,
 specify the AMI, instance type, and subnet. The Molecule driver docs above have more details on what can be set here.
 
 Of special note is that for systemd-based docker images, you will need to use a few extra configuration options; the
-bottom of the docker driver docs (<https://molecule.readthedocs.io/en/latest/configuration.html#docker>) has more details.
+bottom of the docker driver docs ([https://molecule.readthedocs.io/en/latest/configuration.html#docker](https://molecule.readthedocs.io/en/latest/configuration.html#docker)) has more details.
 Since most modern Linux distributions use systemd, you’ll probably need to use this.
 
 If you have other Ansible roles your role is dependent on, be sure to specify this in the `meta/main.yml` file in your
@@ -77,7 +77,7 @@ If this works, you know that at least the Molecule parts are working right.
 ### Testing in EC2
 
 With EC2, there a couple of other steps you’ll need to take. First, you’ll have to define an EC2_REGION environment
-variable like so (this is due to the error described here: <https://github.com/ansible/molecule/issues/1570>):
+variable like so (this is due to the error described here: [https://github.com/ansible/molecule/issues/1570](https://github.com/ansible/molecule/issues/1570)):
 
 > `export EC2_REGION=”us-west-2”`
 
@@ -117,7 +117,7 @@ instances so I could poke around in them when something wasn’t working.
 By default, Molecule is not testing anything other than the accuracy of your Ansible code -- is it written right and
 does it run without generating errors. This doesn’t tell you if it’s actually doing what you want it to, though. For
 that, you’ll need to write additional tests. By default, these use Test-Infra
-(<https://testinfra.readthedocs.io/en/latest/>); you’ll put these in the `molecule/scenario_name/tests` directory. You
+([https://testinfra.readthedocs.io/en/latest/](https://testinfra.readthedocs.io/en/latest/)); you’ll put these in the `molecule/scenario_name/tests` directory. You
 should see a `test_default.py` file there already; this test is an example that just makes sure the `/etc/hosts` file
 and root user exist, which is a bare minimum for things to actually work.
 

diff --git a/docs/infrasec/aws/aws-organizations.md b/docs/infrasec/aws/aws-organizations.md
@@ -1,7 +1,7 @@
 # AWS Organizations
 
 [AWS Organizations](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_introduction.html)
-provide a native way to manage multiple AWS accounts.  They provide
+provide a native way to manage multiple AWS accounts. They provide
 consolidated billing, APIs (e.g., via Terraform) for automating account
 creation, and the ability to apply account-wide IAM like policies.