Problem Description

Template creation in Coder can fail due to various setup and infrastructure requirements, impacting user experience by not providing clear diagnostics to troubleshoot. This is especially critical for new deployments evaluating Coder.

Templates can be created via:

1. CLI: coder templates push.
2. UI: Uploading an archive or selecting built-in templates.

During provisioning, Coder runs terraform plan and terraform apply. Failures may occur due to unmet dependencies, incorrect configurations, or provider authentication issues, but diagnostics are limited, often only showing a generic terraform exit code 1 without specifics. For instance, the Docker template requires:

• Access to the Docker socket.
• Coder user permissions to access the socket.

Failures vary across setups, such as Docker Compose, Kubernetes, and system services, making troubleshooting challenging. Missing diagnostics for Docker socket, permissions, or provider authentication errors contribute to user frustration and delays in setup.

Desired Solution

To improve diagnostics, we need actionable logs, UI hints, and expanded documentation for common setup issues.

1. Enhanced Logging and Diagnostics:

   • Capture specific error points in terraform plan and terraform apply, especially around Docker socket access and provider authentication.
   • Log provider-specific authentication errors (e.g., AWS credentials) and expose them in both logs and UI.

2. UI Feedback and Suggested Fixes:

   • Display Terraform error details in the UI, with actionable guidance based on the issue type:
     • Docker Socket Unavailability: Suggest relevant fixes depending on the environment (Docker Compose, Kubernetes, etc.), such as adding add_groups or setting up Docker group permissions.
     • Provider Authentication Errors: Show hints for authentication failures, like AWS or GCP, and provide links to troubleshooting documentation.

3. Documentation Update:

   • Add troubleshooting guides specific to template creation failures, covering Docker socket access, permissions setup, and provider authentication, with examples for Docker Compose, Kubernetes, and system services.

Implementing these steps will streamline template creation, enabling users to resolve failures independently and improving the initial user experience with Coder.

Related issues:

• Cannot create new template #15710