Upgrade Terraform Module 2.x → 3.0

Module 3.0 is a breaking release driven by two changes:

The module now deploys Helm chart 2.0.0, which restructured credentials under a single secrets: block and removed namespace.name from its values.
The module’s own variables grew to match — new namespace / create_namespace, optional bring-your-own Secret, and a helm_values passthrough.

Module 3.0 requires Helm chart 2.0.0 (now the default). If you pin var.helm_chart_version to a 1.x chart, terraform apply will fail — the module generates values in the 2.x shape (secrets.*) and the old chart won’t recognise them.

Prerequisites

Terraform >= 1.5.0.
AWS provider >= 5.52, Helm provider >= 2.9.0, Kubernetes provider >= 2.13.1 (unchanged from 2.x).
A working module 2.x deployment. The upgrade is a drop-in terraform apply with values migrated.

What’s new

Variable	Purpose	Default
`namespace`	Kubernetes namespace to deploy the scanner into. Rejects `default`.	`"scanner"`
`create_namespace`	Whether Terraform should create the namespace. Set to `false` if managed out-of-band.	`true`
`existing_config_secret`	Name of a pre-existing Opaque Secret with `license-key`, `connector-api-key`, `connector-url`. When set, the chart skips creating `scanner-config`.	`null`
`existing_registry_secret`	Name of a pre-existing `kubernetes.io/dockerconfigjson` Secret. When set, the chart skips creating `detectify-registry`.	`null`
`helm_values`	List of YAML strings appended to the module’s generated values. Customer values take precedence.	`[]`

See Configuration → Passing through extra Helm values and Secrets Management → Bring-your-own Secret for worked examples.

What changed

Chart 2.0 — values shape

You don’t need to know or touch the chart values directly; the module now writes them in the 2.x shape internally. But if you previously passed a pre-rendered values file via some older passthrough mechanism (e.g. forked the module), rewrite it using the chart 1.x → 2.0 migration guide before upgrading.

`var.helm_chart_version` now pinned by default

Module 2.x left var.helm_chart_version = null, which pulled “latest” from the chart repo — so every chart major release silently broke existing deployments. Module 3.0 pins it to "~> 2.0" so you stay on a known-good chart major.

If you’d explicitly set helm_chart_version in your config, leave it; module 3.0 doesn’t change behaviour for you. If you’d relied on the null default, you now get ~> 2.0 automatically.

Credentials are optional when using BYO Secret

var.license_key, var.connector_api_key, var.registry_username, and var.registry_password all default to "" now, so BYO-Secret setups don’t need dummy values. A check "secrets_provided" block asserts that either the inline values or a matching existing_*_secret is set — terraform plan will surface a clear message if neither path is populated.

`namespace.name` in the values blob removed

Previously the module hardcoded namespace.name = "scanner" inside the generated values. Chart 2.0 ignores that field entirely — namespaces now come from helm -n (which the module passes based on var.namespace). Nothing to do unless you’d forked the module.

Migration steps

Bump the module version in your root config:


module "internal_scanner" {
  source  = "detectify/internal-scanning/aws"
  version = "~> 3.0"  # was "~> 2.0"
  # ...
}

(Optional) Set namespace explicitly if you’re relying on the old hardcoded scanner default and want it locked down:
```
module "internal_scanner" {
  # ...
  namespace = "scanner"
}
```
(Optional) Switch to bring-your-own Secrets if you want credentials out of Terraform state:
```
module "internal_scanner" {
  # ...
  existing_config_secret   = "scanner-config"
  existing_registry_secret = "detectify-registry"
}
```
See Secrets Management → Bring-your-own Secret for how to get the Secrets into the cluster.
Run terraform init -upgrade and terraform apply.
```
terraform init -upgrade
terraform plan
terraform apply
```
The Helm release rolls forward in-place. Pods restart with credentials mounted from the 2.x-shaped Secrets. No data loss (Redis PVC is preserved).

Verify:


kubectl get pods -n scanner
kubectl logs -n scanner -l app=scan-scheduler --tail=50

Rollback

Rolling back to module 2.x from a successful 3.0 apply is not recommended — the in-cluster Secrets have been rewritten to the chart 2.x shape and the 1.x chart won’t read them. If you need to roll back, restore the pre-upgrade state file and manifests, then reinstall the chart at 1.x.

Common errors

`secrets.licenseKey is required unless secrets.existingConfigSecret is set.`

Surfaced by the chart when neither inline credentials nor a BYO Secret is available. Verify either var.license_key / var.connector_api_key / var.registry_username / var.registry_password are populated, or var.existing_config_secret / var.existing_registry_secret are set and the named Secrets exist in var.namespace. See Troubleshooting → Helm install validation errors.

`internal-scanning-agent refuses to install into the default namespace.`

You’ve set var.namespace = "default". Pick a different namespace — the module rejects it to match the chart’s install-time guard.

`helm_chart_version` conflict

If terraform plan shows a chart downgrade / unexpected change, you likely have var.helm_chart_version pinned to a 1.x chart. Remove the override (to take the new "~> 2.0" default) or explicitly set it to a 2.x version.

Next Steps

Configuration — Full module reference including helm_values passthrough
Secrets Management — KMS, AWS Secrets Manager, BYO Secret
Troubleshooting — Common issues