Problem
When a new module version (release or tag) is pushed to a version control system (VCS), Terraform Enterprise may fail to automatically update its Private Module Registry with the new version.
Cause
This issue can occur at several stages of the module ingestion process. The root cause is typically a failure in one of the following areas:
- VCS Webhook Delivery: Terraform Enterprise did not receive the update notification from the VCS provider.
- Module Ingress: Terraform Enterprise received the notification but failed to fetch or process the module source code.
- Object Storage: The processed module could not be uploaded to the configured object storage backend.
- Module Validation: The module's code failed syntax or structural validation checks.
Solutions
Follow these solutions sequentially to diagnose and resolve the issue.
Solution 1: Verify VCS Webhook Delivery
Terraform Enterprise relies on webhooks from your VCS provider to receive notifications about new tags. If this webhook delivery fails, Terraform Enterprise is never notified of the new version.
- Check VCS Webhook Logs: Review the webhook delivery logs in your VCS provider's settings to identify any delivery errors.
-
Troubleshoot Common Causes:
- Webhook Misconfiguration: Validate that the webhook URL in your VCS settings matches the one provided in the Terraform Enterprise workspace's Version Control settings.
- Terraform Enterprise Downtime: If Terraform Enterprise was unavailable, retry the webhook delivery from the VCS provider's UI if possible. Otherwise, you may need to delete and re-push the tag to trigger a new event.
-
Network or Firewall Restrictions: Network issues are a common cause of webhook failure. Ensure that your network configuration meets the Terraform Enterprise Network Requirements. Verify that firewalls, security groups, load balancers, and proxies allow traffic between your VCS provider and your Terraform Enterprise instance. Check the
atlasandsidekiqlogs in Terraform Enterprise for network-related errors.
Solution 2: Check Module Ingress and VCS Permissions
After receiving a webhook, the slug-ingress service in Terraform Enterprise fetches and processes the module. Failures at this stage will prevent the module from appearing in the registry.
-
Check Terraform Enterprise Logs: Review the
sidekiqandslug-ingresslogs for processing or ingress errors. -
Troubleshoot Common Causes:
-
Incorrect Module Naming: Ensure the module name and tag format comply with the Terraform Module Registry requirements. Release tags must use semantic versioning (e.g.,
1.0.4orv1.0.4). - Repository Visibility or Permissions: Confirm that the VCS connection configured in Terraform Enterprise has sufficient permissions to access the module repository.
- Expired OAuth Token: Authorization errors in the logs may indicate an expired token. Attempt to reauthorize the VCS provider using the Reauthorizing VCS OAuth Providers guide. If reauthorization fails, you may need to recreate the VCS connection and republish the modules by following the guide to refresh private registry modules after updating a VCS connection.
- Disassociated Module: In some cases, the module can become disassociated from its VCS repository. Deleting and recreating the module in the Terraform Enterprise registry can re-establish the connection.
-
Incorrect Module Naming: Ensure the module name and tag format comply with the Terraform Module Registry requirements. Release tags must use semantic versioning (e.g.,
Solution 3: Confirm Object Storage Uploads
Once ingressed, the archivist service uploads the module version to your configured object storage (e.g., AWS S3, Azure Blob Storage). Failures here will prevent the module from being stored.
-
Check Archivist Logs: Review logs from the
archivistcomponent for errors related to storage uploads. -
Troubleshoot Common Causes:
- Insufficient Storage Permissions: Verify that the IAM role or credentials used by Terraform Enterprise have write permissions for the designated storage bucket.
- Incorrect Storage Configuration: Double-check the object storage endpoint, credentials, and bucket name in your Terraform Enterprise configuration.
- Connectivity Issues: Ensure there is stable, low-latency connectivity between your Terraform Enterprise instance and the object storage provider. Test connectivity by attempting a manual upload.
Solution 4: Review Module Validation Logs
After ingestion, the terraform-registry-worker service validates the module's syntax and structure. If validation fails, the module is rejected.
-
Check Registry Worker Logs: Review the
terraform-registry-workerlogs for specific validation error messages. -
Troubleshoot Common Causes:
-
Syntax Errors: Run
terraform validatelocally within the module's directory to identify and fix any HCL syntax errors. - Dependency Requirements: Ensure that all provider and module dependencies are correctly defined and accessible.
-
Incompatible Terraform Versions: Check the
required_versionconstraint in the module's configuration to ensure it is compatible with the Terraform versions supported by your Terraform Enterprise instance.
-
Syntax Errors: Run
Additional Information
If you have followed all troubleshooting steps and the issue persists, review the application logs for your Terraform Enterprise instance for more detailed error messages that can help pinpoint the failure point.