# Compatibility contract

Source-verified against the linked primary documentation on 2026-09-01. The pins below were not installed or run locally unless a validation report says otherwise. Re-verify and execute the relevant lab checks before upgrading a dependency.

| Component | Course pin, not locally tested | Compatibility range or constraint | Source |
| --- | --- | --- | --- |
| Terraform CLI | 1.16.0 | `>= 1.16.0, < 2.0.0` | [Install Terraform](https://developer.hashicorp.com/terraform/install), [version constraints](https://developer.hashicorp.com/terraform/language/expressions/version-constraints) |
| OpenTofu CLI | 1.12.6 | `>= 1.12.0, < 2.0.0` | [OpenTofu 1.12 documentation](https://opentofu.org/docs/v1.12/), [v1 compatibility promises](https://opentofu.org/docs/language/v1-compatibility-promises/) |
| HashiCorp AWS provider | 6.60.0 | `>= 6.60.0, < 7.0.0` | [AWS provider 6.60.0](https://registry.terraform.io/providers/hashicorp/aws/6.60.0), [provider requirements](https://developer.hashicorp.com/terraform/language/providers/requirements) |
| Amazon EKS | Kubernetes 1.36, platform `eks.6` | EKS standard support: Kubernetes 1.34-1.36 | [EKS Kubernetes lifecycle](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html), [EKS platform versions](https://docs.aws.amazon.com/eks/latest/userguide/platform-versions.html) |
| Envoy Gateway | 1.9.1 | Kubernetes 1.33-1.36; Gateway API 1.6.1 | [Envoy Gateway compatibility matrix](https://gateway.envoyproxy.io/news/releases/matrix/), [1.9.1 release notes](https://gateway.envoyproxy.io/news/releases/notes/v1.9.1/) |
| Karpenter | 1.14.1 | Course NodePool and EC2NodeClass use the stable `v1` APIs | [Karpenter CloudFormation reference](https://karpenter.sh/docs/reference/cloudformation/), [NodeClasses](https://karpenter.sh/docs/concepts/nodeclasses/) |
| AWS Load Balancer Controller | 2.15.0, Helm chart 1.15.0 | Kubernetes 1.22+ | [installation](https://kubernetes-sigs.github.io/aws-load-balancer-controller/latest/deploy/installation/), [2.15 IAM policy](https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.15.0/docs/install/iam_policy.json) |
| Kubernetes Gateway API | 1.6.1 | Bundled and tested by Envoy Gateway 1.9.x | [Envoy Gateway compatibility matrix](https://gateway.envoyproxy.io/news/releases/matrix/) |
| Argo CD | 3.5.0 | Kubernetes 1.33-1.36 | [Argo CD installation and tested versions](https://argo-cd.readthedocs.io/en/stable/operator-manual/installation/) |
| Apache Cassandra | 5.0.9 | Cassandra 5.0.x, maintained until Cassandra 8.0; Java 11 or 17 runtime | [Cassandra downloads](https://cassandra.apache.org/_/download), [Java support](https://cassandra.apache.org/doc/stable/cassandra/reference/java17.html) |
| Go | 1.27.0 | Supported until two newer major Go releases | [Go release history](https://go.dev/doc/devel/release) |
| Helm | 4.2.4 | Kubernetes 1.33.x-1.36.x | [Helm version support policy](https://helm.sh/docs/topics/version_skew/) |
| Kubernetes | 1.36.2 | Upstream maintained release branches: 1.35-1.37 | [Kubernetes releases](https://kubernetes.io/releases/), [version skew policy](https://kubernetes.io/releases/version-skew-policy/) |

Kubernetes 1.37.0 is newer upstream, but this course intentionally targets 1.36.2 because the current EKS, Helm, Envoy Gateway, and Argo CD compatibility matrices have a shared supported ceiling of Kubernetes 1.36.

## Shared-HCL boundary

The course uses one HCL tree. Every shared root must satisfy the Terraform and OpenTofu CLI constraints above. A version-specific feature needs an explicit compatibility note and separate verification with both CLIs; do not silently rely on a feature supported by only one tool.

## Shared S3 backend locking and native tests

The shared S3 backend contract is `use_lockfile = true`. The remote-state lab therefore has a separate shared feature floor of `>= 1.10, < 2.0.0`; provider-neutral labs retain their existing `>= 1.6` floor. Both tools support S3-native locking; DynamoDB locking is deprecated in Terraform and is not used in this course. Keep backend coordinates in an uncommitted partial backend file, include the bootstrap output's `kms_key_id` in it, and enable S3 bucket versioning for recovery. Backend callers need KMS key-policy and IAM permission for `kms:Encrypt`, `kms:Decrypt`, `kms:GenerateDataKey`, and `kms:DescribeKey` on that customer-managed key. The bootstrap root retains local state because it creates the backend resources and cannot safely use the backend it is creating. [Terraform S3 backend](https://developer.hashicorp.com/terraform/language/backend/s3), [OpenTofu S3 backend](https://opentofu.org/docs/language/settings/backends/s3/)

Run the provider-free environment contract tests from the root module:

```sh
terraform -chdir=learn-terraform/labs/07-environments test
tofu -chdir=learn-terraform/labs/07-environments test
```

Both commands execute the same `*.tftest.hcl` file. The tests use `command = plan`, so they do not create cloud resources. [Terraform test](https://developer.hashicorp.com/terraform/cli/commands/test), [OpenTofu test](https://opentofu.org/docs/cli/commands/test/)