Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit c30652f

Browse files
stirbystirby
committed
workspace management
1 parent 71c5c5a commit c30652f

File tree

13 files changed

+164
-28
lines changed

13 files changed

+164
-28
lines changed

‎docs/admin/workspaces/README.md

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,3 +85,52 @@ Enterprise admins may apply bulk operations (update, delete, start, stop) in the
8585
The start and stop operations can only be applied to a set of workspaces which are all in the same state. For update and delete, the user will be prompted for confirmation before any action is taken.
8686

8787
![Bulk workspace actions](../../images/user-guides/workspace-bulk-actions.png)
88+
89+
## Repairing workspaces
90+
91+
Use the following command to re-enter template input variables in an existing
92+
workspace. This command is useful when a workspace fails to build because its
93+
state is out of sync with the template.
94+
95+
```shell
96+
coder update <your workspace name> --always-prompt
97+
```
98+
99+
First, try re-entering parameters from a workspace. In the Coder UI, you can
100+
filter your workspaces using pre-defined filters or employing the Coder's filter
101+
query. Take a look at the following examples to understand how to use the
102+
Coder's filter query:
103+
104+
- To find the workspaces that you own, use the filter `owner:me`.
105+
- To find workspaces that are currently running, use the filter
106+
`status:running`.
107+
108+
![Re-entering template variables](../../images/templates/template-variables.png)
109+
110+
You can also do this in the CLI with the following command:
111+
112+
```shell
113+
coder update <your workspace name> --always-prompt
114+
```
115+
116+
If that does not work, a Coder admin can manually push and pull the Terraform
117+
state for a given workspace. This can lead to state corruption or deleted
118+
resources if you do not know what you are doing.
119+
120+
```shell
121+
coder state pull <username>/<workspace name>
122+
# Make changes
123+
coder state push <username>/<workspace name>
124+
```
125+
126+
## Logging
127+
128+
Coder stores macOS and Linux logs at the following locations:
129+
130+
| Service | Location |
131+
| ----------------- | -------------------------------- |
132+
| `startup_script` | `/tmp/coder-startup-script.log` |
133+
| `shutdown_script` | `/tmp/coder-shutdown-script.log` |
134+
| Agent | `/tmp/coder-agent.log` |
135+
136+
> Note: Logs are truncated once they reach 5MB in size.

‎docs/images/user-guides/terminal-access.png

788 KB
Loading

‎docs/images/autostart.png renamed to ‎docs/images/workspaces/autostart.png

File renamed without changes.

‎docs/images/autostop.png renamed to ‎docs/images/workspaces/autostop.png

File renamed without changes.

‎docs/manifest.json

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -130,6 +130,12 @@
130130
}
131131
]
132132
},
133+
{
134+
"title": "Workspace Management",
135+
"description": "Manage workspaces",
136+
"path": "./user-guides/workspace-management.md"
137+
// "icon_path": "./images/icons/.svg"
138+
},
133139
{
134140
"title": "Workspace Scheduling",
135141
"description": "Cost control with workspace schedules",

‎docs/user-guides/README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# User Guides
22

3-
These guides contain information on workspace access via IDEs, environment personalization, and workspace scheduling.
3+
These guides contain information on workspace management, workspace access via IDEs, environment personalization, and workspace scheduling.
44

55
These are intended for end-user flows only. If you are an administrator, please refer to our docs on configuring [templates](../admin/README.md) or the [control plane](../admin/README.md).
66

‎docs/user-guides/workspace-access/README.md

Lines changed: 3 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -8,18 +8,12 @@ You can see the primary methods of connecting to your workspace in the workspace
88

99
![Workspace View](../../images/user-guides/workspace-view-connection-annotated.png)
1010

11-
<!-- ## Coder Apps
12-
13-
TODO: Is this relevant?
14-
15-
Coder Apps (from our [`coder_app`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/app) resource in terraform) provide IDE connections and the Terminal. Coder Apps can connect you to ports or run commands on the remote workspace. They be shared with other users by copying the URL from the button. Contact your template administrator if you have IDEs or tools you'd like added into your workspace.
16-
17-
, and can be extended with our [Module Registry](https://registry.coder.com/modules). -->
18-
1911
## Terminal
2012

2113
The terminal is implicitly enabled in Coder and allows you to access your workspace through the shell environment set by your template.
2214

15+
![Terminal Access](../../images/user-guides/terminal-access.png)
16+
2317
## SSH
2418

2519
### Through with the CLI
@@ -96,9 +90,7 @@ VS Code in the web browser. You can read more in our [documentation for code-ser
9690

9791
## Other Web IDEs
9892

99-
<!-- TODO: update template guides link -->
100-
101-
We support a variety of other browser IDEs and tools to interact with your workspace. Each of these can be configured by your template admin using our [Web IDE guides](../../admin/templates/README.md).
93+
We support a variety of other browser IDEs and tools to interact with your workspace. Each of these can be configured by your template admin using our [Web IDE guides](../../admin/templates/extending-templates/web-ides.md).
10294

10395
Supported IDEs:
10496

@@ -116,8 +108,6 @@ You can manage listening ports on your workspace page through with the listening
116108

117109
You can also [share ports](./port-forwarding.md#sharing-ports) with other users, or [port-forward](./port-forwarding.md#the-coder-port-forward-command) through the CLI with `coder port forward`. Read more in the [docs on workspace ports](./port-forwarding.md).
118110

119-
<!-- TODO: Outdated screenshot -->
120-
121111
![Open Ports window](../../images/networking/listeningports.png)
122112

123113
## Remote Desktops

‎docs/user-guides/workspace-access/port-forwarding.md

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,6 @@
22

33
## Port forwarding
44

5-
<!-- TODO: Potentially break port management into subsection -->
6-
75
Port forwarding lets developers securely access processes on their Coder
86
workspace from a local machine. A common use case is testing web applications in
97
a browser.

‎docs/user-guides/workspace-maintenance.md

Lines changed: 0 additions & 7 deletions
This file was deleted.

‎docs/user-guides/workspace-management.md

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# Workspaces
2+
3+
A workspace is the environment that a developer works in. Developers in a team
4+
each work from their own workspace and can use
5+
[multiple IDEs](./workspace-access/README.md).
6+
7+
A developer creates a workspace from a
8+
[shared template](../admin/templates/README.md). This lets an entire team work
9+
in environments that are identically configured and provisioned with the same
10+
resources.
11+
12+
## Creating workspaces
13+
14+
You can create a workspace in the UI. Log in to your Coder instance, go to the
15+
**Templates** tab, find the template you need, and select **Create Workspace**.
16+
17+
![Creating a workspace in the UI](./images/creating-workspace-ui.png)
18+
19+
When you create a workspace, you will be prompted to give it a name. You might
20+
also be prompted to set some parameters that the template provides.
21+
22+
You can manage your existing templates in the **Workspaces** tab.
23+
24+
You can also create a workspace from the command line:
25+
26+
Each Coder user has their own workspaces created from
27+
[templates](./admin/templates/README.md):
28+
29+
```shell
30+
# create a workspace from the template; specify any variables
31+
coder create --template="<templateName>" <workspaceName>
32+
33+
# show the resources behind the workspace and how to connect
34+
coder show <workspace-name>
35+
```
36+
37+
## Workspace filtering
38+
39+
In the Coder UI, you can filter your workspaces using pre-defined filters or
40+
Coder's filter query. Filters follow the pattern `[filter name]:[filter text]`
41+
and multiple filters can be specified separated by a space i.e
42+
`owner:me status:running`
43+
44+
The following filters are supported:
45+
46+
- `owner` - Represents the `username` of the owner. You can also use `me` as a
47+
convenient alias for the logged-in user, e.g., `owner:me`
48+
- `name` - Name of the workspace.
49+
- `template` - Name of the template.
50+
- `status` - Indicates the status of the workspace, e.g, `status:failed` For a
51+
list of supported statuses, see
52+
[WorkspaceStatus documentation](https://pkg.go.dev/github.com/coder/coder/codersdk#WorkspaceStatus).
53+
- `outdated` - Filters workspaces using an outdated template version, e.g,
54+
`outdated:true`
55+
- `dormant` - Filters workspaces based on the dormant state, e.g `dormant:true`
56+
- `has-agent` - Only applicable for workspaces in "start" transition. Stopped
57+
and deleted workspaces don't have agents. List of supported values
58+
`connecting|connected|timeout`, e.g, `has-agent:connecting`
59+
- `id` - Workspace UUID
60+
61+
### Automatic updates
62+
63+
It can be tedious to manually update a workspace everytime an update is pushed
64+
to a template. Users can choose to opt-in to automatic updates to update to the
65+
active template version whenever the workspace is started.
66+
67+
Note: If a template is updated such that new parameter inputs are required from
68+
the user, autostart will be disabled for the workspace until the user has
69+
manually updated the workspace.
70+
71+
![Automatic Updates](./images/workspace-automatic-updates.png)
72+
73+
## Starting and stopping workspaces
74+
75+
By default, you manually start and stop workspaces as you need. You can also
76+
schedule a workspace to start and stop automatically.
77+
78+
To set a workspace's schedule, go to the workspace, then **Settings** >
79+
**Schedule**.
80+
81+
![Scheduling UI](./images/schedule.png)
82+
83+
Coder might also stop a workspace automatically if there is a
84+
[template update](./admin/templates/README.md#Start/stop) available.
85+
86+
Learn more about [workspace lifecycle](../admin/workspaces/lifecycle.md) and our
87+
[scheduling features](./workspace-scheduling.md).
88+
89+
## Workspace resources
90+
91+
Workspaces in Coder are started and stopped, often based on whether there was
92+
any activity or if there was a [template update](./admin/templates/README.md)
93+
available.
94+
95+
Resources are often destroyed and re-created when a workspace is restarted,
96+
though the exact behavior depends on the template. For more information, see
97+
[Resource Persistence](./admin/templates/extending-templates/resource-persistence.md).

‎docs/user-guides/workspace-scheduling.md

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,8 @@ Use autostart to start a workspace at a specified time and which days of the
3030
week. Also, you can choose your preferred timezone. Admins may restrict which
3131
days of the week your workspace is allowed to autostart.
3232

33+
![Autostart UI](../images/workspaces/autostart.png)
34+
3335
## Autostop
3436

3537
Use autostop to stop a workspace after a number of hours. Autostop won't stop a
@@ -39,7 +41,7 @@ modify the inactivity timeout duration with the
3941
[inactivity bump](#inactivity-timeout) template setting. Coder checks for active
4042
connections in the IDE, SSH, Port Forwarding, and coder_app.
4143

42-
![Autostop UI](../images/autostop.png)
44+
![Autostop UI](../images/workspaces/autostop.png)
4345

4446
## Inactivity timeout
4547

@@ -106,4 +108,3 @@ workspaces will remain in the dormant state before automatic deletion.
106108

107109
Enterprise admins may also configure failure cleanup, which will automatically
108110
delete workspaces that remain in a `failed` state for too long.
109-

‎docs/workspaces.md

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,10 @@
11
# Workspaces
22

3-
<!-- TODO: ENSURE THIS CONTENT IS COPIED IN RESTRUCTURE -->
3+
<!-- TODO: audit
4+
- Creating workspaces -> user-guides/workspace-management.md
5+
- Filtering workspaces -> user-guides/workspace-management.md
6+
- Starting and Stopping workspaces -> user-guides/workspace-management.md -> user-guides/workspace-scheduling.md
7+
-->
48

59
A workspace is the environment that a developer works in. Developers in a team
610
each work from their own workspace and can use

‎examples/templates/aws-linux/README.md

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,6 @@ tags: [vm, linux, aws, persistent-vm]
1111

1212
Provision AWS EC2 VMs as [Coder workspaces](https://coder.com/docs/workspaces) with this example template.
1313

14-
<!-- TODO: Add screenshot -->
15-
1614
## Prerequisites
1715

1816
### Authentication

0 commit comments

Comments
 (0)