Terraform module registry runbook
Summary
Section titled “Summary”The Terraform Module Registry allows you to publish and share Terraform modules within your GitLab instance.
Note: For general Package Registry architecture, troubleshooting, and operational procedures, see the main Package Registry runbook.
- Project level:
/api/v4/projects/:id/packages/terraform/modules - Namespace level:
/api/v4/packages/terraform/modules/v1/:module_namespace/
Observability
Section titled “Observability”Troubleshooting
Section titled “Troubleshooting”Common problems
Section titled “Common problems”Module resolution errors
Section titled “Module resolution errors”Summary
Terraform cannot resolve module addresses due to naming constraints or version issues.
Symptoms:
- Error: “Invalid version constraint”
- Error: “Module not found”
- Error: “Cannot apply a version constraint to module because it has a non Registry URL”
Steps to Diagnose:
- Check module naming conventions (namespace, module name, system)
- Verify namespace doesn’t contain unsupported characters (dots)
- Check version format and constraints
Troubleshooting:
- Verify namespace doesn’t contain dots (.) - Terraform limitation
- Module versions should follow the semantic versioning specification.
Resolution:
- Avoid dots in namespace names
- Use proper semantic versioning
References