Skip to content

docs: Clarify access_url format in workspace data source documentation #430

@blink-so

Description

@blink-so

Problem

The current documentation for the access_url field in the coder_workspace data source doesn't specify the exact format, particularly whether it includes a trailing slash or not. This creates confusion for users who need to build URLs using this value.

As mentioned in the Terraform registry documentation, users currently have to guess and check to figure out the correct format.

Solution

The documentation should be updated to:

  1. Clarify the format: Specify that access_url is the base URL without a trailing slash
  2. Provide examples: Show concrete examples like https://coder.example.com and https://coder.example.com:8080
  3. Add usage patterns: Demonstrate common use cases for building API endpoints and resource URLs

Proposed Changes

Update docs/data-sources/workspace.md to:

1. Update the field description:

- `access_url` (String) The access URL of the Coder deployment provisioning this workspace. This is the base URL without a trailing slash (e.g., `https://coder.example.com` or `https://coder.example.com:8080`).

2. Add a "Common Usage Patterns" section:

## Common Usage Patterns

### Using access_url for API calls

```terraform
# The access_url provides the base URL without trailing slash
locals {
  api_endpoint = "${data.coder_workspace.me.access_url}/api/v2"
  workspace_url = "${data.coder_workspace.me.access_url}/@${data.coder_workspace_owner.me.name}/${data.coder_workspace.me.name}"
}

Building URLs for workspace resources

# For icons and static resources, append the path directly
resource "coder_metadata" "info" {
  resource_id = coder_agent.main.id
  icon        = "${data.coder_workspace.me.access_url}/icon/database.svg"
}

### 3. Add clarifying comment in the main example:
```terraform
# Note: access_url provides the base URL without trailing slash (e.g., "https://coder.example.com")

Evidence

Based on the codebase analysis:

  • In provider/workspace.go, the access_url is set using config.URL.String() which returns the URL without trailing slash
  • In provider/workspace_test.go, the test expects "https://example.com:8080" (no trailing slash)
  • In the main Coder repository (coderd/initscript.go), when the access URL is used, a trailing slash is explicitly added: api.AccessURL.String()+"/"

This confirms that the access_url field contains the base URL without a trailing slash.

Impact

This change will:

  • Eliminate confusion for users building URLs with access_url
  • Provide clear examples of the expected format
  • Reduce support requests and trial-and-error development
  • Improve the overall developer experience with the Terraform provider

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions