Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

feat(docs): add docs for external workspaces#19437

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.

Already on GitHub?Sign in to your account

Merged
kacpersaw merged 9 commits intomainfromkacpersaw/external-workspaces-docs
Aug 28, 2025
Merged
Show file tree
Hide file tree
Changes fromall commits
Commits
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletionsdocs/admin/templates/index.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -61,5 +61,6 @@ needs of different teams.
changes are reviewed and tested.
- [Permissions and Policies](./template-permissions.md): Control who may access
and modify your template.
- [External Workspaces](./managing-templates/external-workspaces.md): Learn how to connect your existing infrastructure to Coder workspaces.

<children></children>
131 changes: 131 additions & 0 deletionsdocs/admin/templates/managing-templates/external-workspaces.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
# External Workspaces

External workspaces allow you to seamlessly connect externally managed infrastructure as Coder workspaces. This enables you to integrate existing servers, on-premises systems, or any capable machine with the Coder environment, ensuring a smooth and efficient development workflow without requiring Coder to provision additional compute resources.

## Prerequisites

- Access to external compute resources that can run the Coder agent:
- **Windows**: amd64 or arm64 architecture
- **Linux**: amd64, arm64, or armv7 architecture
- **macOS**: amd64 or arm64 architecture
- **Examples**: VMs, bare-metal servers, Kubernetes nodes, or any machine meeting the above requirements.
- Networking access to your Coder deployment.
- A workspace template that includes a [`coder_external_agent`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/external_agent) resource.

We provide an example template on how to set up external workspaces in the [Coder Registry](https://registry.coder.com/templates/coder-labs/externally-managed-workspace)

## Benefits

External workspaces offer flexibility and control in complex environments:

- **Incremental adoption of Coder**

Integrate with existing infrastructure gradually without needing to migrate everything at once. This is particularly useful when gradually migrating worklods to Coder without refactoring current infrastructure.

- **Flexibility**

Attach cloud, hybrid, or on-premises machines as developer workspaces. This enables connecting existing on-premises GPU servers for ML development or bringing manually provisioned VMs in restricted networks under Coder's workspace management.

- **Separation of concerns**

Provision compute resources externally (using your existing IaC or manual processes) while managing workspace configuration (apps, scripts) with Terraform. This approach is ideal for running agents in CI pipelines to provision short-lived, externally managed workspaces for testing or build automation.

## Known limitations

- **Lifecycle control**

Start/stop/restart actions in the Coder UI are disabled for external workspaces.
- **No automatic deprovisioning**

Deleting an external workspace in Coder removes the agent token and record, but does not delete the underlying compute resource.
- **Manual agent management**

Administrators are responsible for deploying and maintaining agents on external resources.
- **Limited UI indicators**

External workspaces are marked in the UI, but underlying infrastructure health is not monitored by Coder.

## When to use it?

Use external workspaces if:

- You have compute resources provisioned outside of Coder’s Terraform flows.
- You want to connect specialized or legacy systems to your Coder deployment.
- You are migrating incrementally to Coder and need hybrid support.
- You need finer control over how and where agents run, while still benefiting from Coder’s workspace experience.

## How to use it?

You can create and manage external workspaces using either the **CLI** or the **UI**.

<div class="tabs">

## CLI

1. **Create an external workspace**

```bash
coder external-workspaces create hello-world \
--template=externally-managed-workspace -y
```

- Validates that the template includes a `coder_external_agent` resource.
- Once created, the workspace is registered in Coder but marked as requiring an external agent.

2. **List external workspaces**

```bash
coder external-workspaces list
```

Example output:

```bash
WORKSPACE TEMPLATE STATUS HEALTHY LAST BUILT CURRENT VERSION OUTDATED
hello-world externally-managed-workspace Started true 15m happy_mendel9 false
```

3. **Retrieve agent connection instructions**

Use this command to query the script you must run on the external machine:

```bash
coder external-workspaces agent-instructions hello-world
```

Example:

```bash
Please run the following command to attach external agent to the workspace hello-world:

curl -fsSL "https://<DEPLOYMENT_URL>/api/v2/init-script/linux/amd64" | CODER_AGENT_TOKEN="<token>" sh
```

You can also output JSON for automation:

```bash
coder external-workspaces agent-instructions hello-world --output=json
```

```json
{
"workspace_name": "hello-world",
"agent_name": "main",
"auth_type": "token",
"auth_token": "<token>",
"init_script": "curl -fsSL \"https://<DEPLOYMENT_URL>/api/v2/init-script/linux/arm64\" | CODER_AGENT_TOKEN=\"<token>\" sh"
}
```

## UI

1. Import the external workspace template (see prerequisites).
2. In the Coder UI, go to **Workspaces → New workspace** and select the imported template.
3. Once the workspace is created, Coder will display **connection details** with the command users need to run on the external machine to start the agent.
4. The workspace will appear in the dashboard, but with the following differences:
- **Start**, **Stop**, and **Restart** actions are disabled.
- Users are provided with instructions for launching the agent manually on the external machine.

![External Workspace View](../../../images/admin/templates/external-workspace.png)

</div>
View file
Open in desktop
Loading
Sorry, something went wrong.Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
6 changes: 6 additions & 0 deletionsdocs/manifest.json
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -519,6 +519,12 @@
"title": "Workspace Scheduling",
"description": "Learn how to control how workspaces are started and stopped",
"path": "./admin/templates/managing-templates/schedule.md"
},
{
"title": "External Workspaces",
"description": "Learn how to manage external workspaces",
"path": "./admin/templates/managing-templates/external-workspaces.md",
"state": ["early access"]
}
]
},
Expand Down
Loading
[8]ページ先頭
©2009-2025 Movatter.jp