opensource/coder
3
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2026-09-24 15:04:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: move api and cli docs routes to reference/ (#14241)

Browse Source
This commit is contained in:
Muhammad Atif Ali
2024-08-13 18:39:46 +03:00
committed by GitHub
parent 6f9b1a39f4
commit 48f29a1995
145 changed files with 4121 additions and 3448 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/admin/audit-logs.md
+5 -3
View File
@@ -70,14 +70,15 @@ audit trails.
Audit logs can be accessed through our REST API. You can find detailed
information about this in our
[endpoint documentation](../api/audit.md#get-audit-logs).
[endpoint documentation](../reference/api/audit.md#get-audit-logs).
## Service Logs
Audit trails are also dispatched as service logs and can be captured and
categorized using any log management tool such as [Splunk](https://splunk.com).
Example of a [JSON formatted](../cli/server.md#--log-json) audit log entry:
Example of a [JSON formatted](../reference/cli/server.md#--log-json) audit log
entry:
```json
{
@@ -112,7 +113,8 @@ Example of a [JSON formatted](../cli/server.md#--log-json) audit log entry:
}
```
Example of a [human readable](../cli/server.md#--log-human) audit log entry:
Example of a [human readable](../reference/cli/server.md#--log-human) audit log
entry:
```console
2023-06-13 03:43:29.233 [info] coderd: audit_log ID=95f7c392-da3e-480c-a579-8909f145fbe2 Time="2023-06-13T03:43:29.230422Z" UserID=6c405053-27e3-484a-9ad7-bcb64e7bfde6 OrganizationID=00000000-0000-0000-0000-000000000000 Ip=<nil> UserAgent=<nil> ResourceType=workspace_build ResourceID=988ae133-5b73-41e3-a55e-e1e9d3ef0b66 ResourceTarget="" Action=start Diff="{}" StatusCode=200 AdditionalFields="{\"workspace_name\":\"linux-container\",\"build_number\":\"7\",\"build_reason\":\"initiator\",\"workspace_owner\":\"\"}" RequestID=9682b1b5-7b9f-4bf2-9a39-9463f8e41cd6 ResourceIcon=""
docs/admin/auth.md
+1 -1
View File
@@ -19,7 +19,7 @@ First,
GitHub will ask you for the following Coder parameters:
- **Homepage URL**: Set to your Coder deployments
[`CODER_ACCESS_URL`](../cli/server.md#--access-url) (e.g.
[`CODER_ACCESS_URL`](../reference/cli/server.md#--access-url) (e.g.
`https://coder.domain.com`)
- **User Authorization Callback URL**: Set to `https://coder.domain.com`
docs/admin/automation.md
+9 -8
View File
@@ -4,8 +4,8 @@ All actions possible through the Coder dashboard can also be automated as it
utilizes the same public REST API. There are several ways to extend/automate
Coder:
- [CLI](../cli.md)
- [REST API](../api/)
- [CLI](../reference/cli/README.md)
- [REST API](../reference/api/README.md)
- [Coder SDK](https://pkg.go.dev/github.com/coder/coder/v2/codersdk)
## Quickstart
@@ -32,9 +32,10 @@ curl https://coder.example.com/api/v2/workspaces?q=owner:me \
## Documentation
We publish an [API reference](../api/index.md) in our documentation. You can
also enable a [Swagger endpoint](../cli/server.md#--swagger-enable) on your
Coder deployment.
We publish an [API reference](../reference/api/README.md) in our documentation.
You can also enable a
[Swagger endpoint](../reference/cli/server.md#--swagger-enable) on your Coder
deployment.
## Use cases
@@ -52,8 +53,8 @@ payloads, we recommend checking the CLI and API documentation.
Workspace agents have a special token that can send logs, metrics, and workspace
activity.
- [Custom workspace logs](../api/agents.md#patch-workspace-agent-logs): Expose
messages prior to the Coder init script running (e.g. pulling image, VM
- [Custom workspace logs](../reference/api/agents.md#patch-workspace-agent-logs):
Expose messages prior to the Coder init script running (e.g. pulling image, VM
starting, restoring snapshot).
[coder-logstream-kube](https://github.com/coder/coder-logstream-kube) uses
this to show Kubernetes events, such as image pulls or ResourceQuota
@@ -73,7 +74,7 @@ activity.
}"
```
- [Manually send workspace activity](../api/agents.md#submit-workspace-agent-stats):
- [Manually send workspace activity](../reference/api/agents.md#submit-workspace-agent-stats):
Keep a workspace "active," even if there is not an open connection (e.g. for a
long-running machine learning job).
docs/admin/configure.md
+6 -5
View File
@@ -1,6 +1,6 @@
Coder server's primary configuration is done via environment variables. For a
full list of the options, run `coder server --help` or see our
[CLI documentation](../cli/server.md).
[CLI documentation](../reference/cli/server.md).
## Access URL
@@ -48,10 +48,11 @@ If you are providing TLS certificates directly to the Coder server, either
1. Use a single certificate and key for both the root and wildcard domains.
2. Configure multiple certificates and keys via
[`coder.tls.secretNames`](https://github.com/coder/coder/blob/main/helm/coder/values.yaml)
in the Helm Chart, or [`--tls-cert-file`](../cli/server.md#--tls-cert-file)
and [`--tls-key-file`](../cli/server.md#--tls-key-file) command line options
(these both take a comma separated list of files; list certificates and their
respective keys in the same order).
in the Helm Chart, or
[`--tls-cert-file`](../reference/cli/server.md#--tls-cert-file) and
[`--tls-key-file`](../reference/cli/server.md#--tls-key-file) command line
options (these both take a comma separated list of files; list certificates
and their respective keys in the same order).
## TLS & Reverse Proxy
docs/admin/encryption.md
+16 -14
View File
@@ -7,7 +7,7 @@ preventing attackers with database access from using them to impersonate users.
## How it works
Coder allows administrators to specify
[external token encryption keys](../cli/server.md#external-token-encryption-keys).
[external token encryption keys](../reference/cli/server.md#external-token-encryption-keys).
If configured, Coder will use these keys to encrypt external user tokens before
storing them in the database. The encryption algorithm used is AES-256-GCM with
a 32-byte key length.
@@ -47,7 +47,7 @@ Additional database fields may be encrypted in the future.
- Ensure you have a valid backup of your database. **Do not skip this step.** If
you are using the built-in PostgreSQL database, you can run
[`coder server postgres-builtin-url`](../cli/server_postgres-builtin-url.md)
[`coder server postgres-builtin-url`](../reference/cli/server_postgres-builtin-url.md)
to get the connection URL.
- Generate a 32-byte random key and base64-encode it. For example:
@@ -90,7 +90,7 @@ if you need to rotate keys, you can perform the following procedure:
- Generate a new encryption key following the same procedure as above.
- Add the above key to the list of
[external token encryption keys](../cli/server.md#--external-token-encryption-keys).
[external token encryption keys](../reference/cli/server.md#--external-token-encryption-keys).
**The new key must appear first in the list**. For example, in the Kubernetes
secret created above:
@@ -110,13 +110,13 @@ data:
encrypted with the old key(s).
- To re-encrypt all encrypted database fields with the new key, run
[`coder server dbcrypt rotate`](../cli/server_dbcrypt_rotate.md). This command
will re-encrypt all tokens with the specified new encryption key. We recommend
performing this action during a maintenance window.
[`coder server dbcrypt rotate`](../reference/cli/server_dbcrypt_rotate.md).
This command will re-encrypt all tokens with the specified new encryption key.
We recommend performing this action during a maintenance window.
> Note: this command requires direct access to the database. If you are using
> the built-in PostgreSQL database, you can run
> [`coder server postgres-builtin-url`](../cli/server_postgres-builtin-url.md)
> [`coder server postgres-builtin-url`](../reference/cli/server_postgres-builtin-url.md)
> to get the connection URL.
- Once the above command completes successfully, remove the old encryption key
@@ -132,8 +132,9 @@ To disable encryption, perform the following actions:
- Stop all active coderd instances. This will prevent new encrypted data from
being written, which may cause the next step to fail.
- Run [`coder server dbcrypt decrypt`](../cli/server_dbcrypt_decrypt.md). This
command will decrypt all encrypted user tokens and revoke all active
- Run
[`coder server dbcrypt decrypt`](../reference/cli/server_dbcrypt_decrypt.md).
This command will decrypt all encrypted user tokens and revoke all active
encryption keys.
> Note: for `decrypt` command, the equivalent environment variable for
@@ -142,7 +143,7 @@ To disable encryption, perform the following actions:
> to help prevent accidentally decrypting data.
- Remove all
[external token encryption keys](../cli/server.md#--external-token-encryption-keys)
[external token encryption keys](../reference/cli/server.md#--external-token-encryption-keys)
from Coder's configuration.
- Start coderd. You can now safely delete the encryption keys from your secret
@@ -159,12 +160,13 @@ To delete all encrypted data from your database, perform the following actions:
- Stop all active coderd instances. This will prevent new encrypted data from
being written.
- Run [`coder server dbcrypt delete`](../cli/server_dbcrypt_delete.md). This
command will delete all encrypted user tokens and revoke all active encryption
keys.
- Run
[`coder server dbcrypt delete`](../reference/cli/server_dbcrypt_delete.md).
This command will delete all encrypted user tokens and revoke all active
encryption keys.
- Remove all
[external token encryption keys](../cli/server.md#--external-token-encryption-keys)
[external token encryption keys](../reference/cli/server.md#--external-token-encryption-keys)
from Coder's configuration.
- Start coderd. You can now safely delete the encryption keys from your secret
docs/admin/healthcheck.md
+16 -14
View File
@@ -4,7 +4,8 @@ Coder includes an operator-friendly deployment health page that provides a
number of details about the health of your Coder deployment.
You can view it at `https://${CODER_URL}/health`, or you can alternatively view
the [JSON response directly](../api/debug.md#debug-info-deployment-health).
the
[JSON response directly](../reference/api/debug.md#debug-info-deployment-health).
The deployment health page is broken up into the following sections:
@@ -106,8 +107,8 @@ query fails.
_Database Latency High_
**Problem:** This code is returned if the median latency is higher than the
[configured threshold](../cli/server.md#--health-check-threshold-database). This
may not be an error as such, but is an indication of a potential issue.
[configured threshold](../reference/cli/server.md#--health-check-threshold-database).
This may not be an error as such, but is an indication of a potential issue.
**Solution:** Investigate the sizing of the configured database with regard to
Coder's current activity and usage. It may be necessary to increase the
@@ -117,18 +118,19 @@ configured threshold to a higher value (this will not address the root cause).
> [!TIP]
>
> - You can enable
> [detailed database metrics](../cli/server.md#--prometheus-collect-db-metrics)
> [detailed database metrics](../reference/cli/server.md#--prometheus-collect-db-metrics)
> in Coder's Prometheus endpoint.
> - If you have [tracing enabled](../cli/server.md#--trace), these traces may
> also contain useful information regarding Coder's database activity.
> - If you have [tracing enabled](../reference/cli/server.md#--trace), these
> traces may also contain useful information regarding Coder's database
> activity.
## DERP
Coder workspace agents may use
[DERP (Designated Encrypted Relay for Packets)](https://tailscale.com/blog/how-tailscale-works/#encrypted-tcp-relays-derp)
to communicate with Coder. This requires connectivity to a number of configured
[DERP servers](../cli/server.md#--derp-config-path) which are used to relay
traffic between Coder and workspace agents. Coder periodically queries the
[DERP servers](../reference/cli/server.md#--derp-config-path) which are used to
relay traffic between Coder and workspace agents. Coder periodically queries the
health of its configured DERP servers and may return one or more of the
following:
@@ -146,7 +148,7 @@ misconfigured reverse HTTP proxy. Additionally, while workspace users should
still be able to reach their workspaces, connection performance may be degraded.
> **Note:** This may also be shown if you have
> [forced websocket connections for DERP](../cli/server.md#--derp-force-websockets).
> [forced websocket connections for DERP](../reference/cli/server.md#--derp-force-websockets).
**Solution:** ensure that any proxies you use allow connection upgrade with the
`Upgrade: derp` header.
@@ -179,9 +181,9 @@ to establish [direct connections](../networking/stun.md). Without at least one
working STUN server, direct connections may not be possible.
**Solution:** Ensure that the
[configured STUN severs](../cli/server.md#derp-server-stun-addresses) are
reachable from Coder and that UDP traffic can be sent/received on the configured
port.
[configured STUN severs](../reference/cli/server.md#derp-server-stun-addresses)
are reachable from Coder and that UDP traffic can be sent/received on the
configured port.
### ESTUN02
@@ -292,8 +294,8 @@ be built until there is at least one provisioner daemon running.
If you are using
[External Provisioner Daemons](./provisioners.md#external-provisioners), ensure
that they are able to successfully connect to Coder. Otherwise, ensure
[`--provisioner-daemons`](../cli/server.md#provisioner-daemons) is set to a
value greater than 0.
[`--provisioner-daemons`](../reference/cli/server.md#provisioner-daemons) is set
to a value greater than 0.
> Note: This may be a transient issue if you are currently in the process of
> updating your deployment.
docs/admin/provisioners.md
+15 -15
View File
@@ -1,9 +1,9 @@
# External provisioners
By default, the Coder server runs
[built-in provisioner daemons](../cli/server.md#provisioner-daemons), which
execute `terraform` during workspace and template builds. However, there are
sometimes benefits to running external provisioner daemons:
[built-in provisioner daemons](../reference/cli/server.md#provisioner-daemons),
which execute `terraform` during workspace and template builds. However, there
are sometimes benefits to running external provisioner daemons:
- **Secure build environments:** Run build jobs in isolated containers,
preventing malicious templates from gaining shell access to the Coder host.
@@ -26,40 +26,40 @@ For example, running 30 provisioner containers will allow 30 users to start
workspaces at the same time.
Provisioners are started with the
[coder provisionerd start](../cli/provisionerd_start.md) command.
[coder provisionerd start](../reference/cli/provisionerd_start.md) command.
## Authentication
The provisioner daemon must authenticate with your Coder deployment.
Set a
[provisioner daemon pre-shared key (PSK)](../cli/server.md#--provisioner-daemon-psk)
[provisioner daemon pre-shared key (PSK)](../reference/cli/server.md#--provisioner-daemon-psk)
on the Coder server and start the provisioner with
`coder provisionerd start --psk <your-psk>`. If you are
[installing with Helm](../install/kubernetes.md#install-coder-with-helm), see
the [Helm example](#example-running-an-external-provisioner-with-helm) below.
> Coder still supports authenticating the provisioner daemon with a
> [token](../cli.md#--token) from a user with the Template Admin or Owner role.
> This method is deprecated in favor of the PSK, which only has permission to
> access provisioner daemon APIs. We recommend migrating to the PSK as soon as
> practical.
> [token](../reference/cli/README.md#--token) from a user with the Template
> Admin or Owner role. This method is deprecated in favor of the PSK, which only
> has permission to access provisioner daemon APIs. We recommend migrating to
> the PSK as soon as practical.
## Types of provisioners
Provisioners can broadly be categorized by scope: `organization` or `user`. The
scope of a provisioner can be specified with
[`-tag=scope=<scope>`](../cli/provisionerd_start.md#t---tag) when starting the
provisioner daemon. Only users with at least the
[`-tag=scope=<scope>`](../reference/cli/provisionerd_start.md#t---tag) when
starting the provisioner daemon. Only users with at least the
[Template Admin](../admin/users.md#roles) role or higher may create
organization-scoped provisioner daemons.
There are two exceptions:
- [Built-in provisioners](../cli/server.md#provisioner-daemons) are always
organization-scoped.
- [Built-in provisioners](../reference/cli/server.md#provisioner-daemons) are
always organization-scoped.
- External provisioners started using a
[pre-shared key (PSK)](../cli/provisionerd_start.md#psk) are always
[pre-shared key (PSK)](../reference/cli/provisionerd_start.md#psk) are always
organization-scoped.
### Organization-Scoped Provisioners
@@ -270,7 +270,7 @@ docker run --rm -it \
As mentioned above, the Coder server will run built-in provisioners by default.
This can be disabled with a server-wide
[flag or environment variable](../cli/server.md#provisioner-daemons).
[flag or environment variable](../reference/cli/server.md#provisioner-daemons).
```shell
coder server --provisioner-daemons=0
docs/admin/scaling/scale-testing.md
+4 -3
View File
@@ -112,13 +112,14 @@ on the workload size to ensure deployment stability.
#### CPU and memory usage
Enabling [agent stats collection](../../cli.md#--prometheus-collect-agent-stats)
Enabling
[agent stats collection](../../reference/cli/server.md#--prometheus-collect-agent-stats)
(optional) may increase memory consumption.
Enabling direct connections between users and workspace agents (apps or SSH
traffic) can help prevent an increase in CPU usage. It is recommended to keep
[this option enabled](../../cli.md#--disable-direct-connections) unless there
are compelling reasons to disable it.
[this option enabled](../../reference/cli/server.md#--disable-direct-connections)
unless there are compelling reasons to disable it.
Inactive users do not consume Coder resources.
docs/admin/workspace-proxies.md
+2 -2
View File
@@ -26,8 +26,8 @@ Workspace proxies can be used in the browser by navigating to the user
## Requirements
- The [Coder CLI](../cli.md) must be installed and authenticated as a user with
the Owner role.
- The [Coder CLI](../reference/cli/README.md) must be installed and
authenticated as a user with the Owner role.
## Step 1: Create the proxy