chore(installation): worker registration docs (#354)

* chore(installation): worker registration docs * add worker registration token to the api docs * correct cli args * fix goofy newlines * one more --------- Co-authored-by: David May <49894298+wass3rw3rk@users.noreply.github.com>
go-vela · Apr 25, 2023 · d89ba33 · d89ba33
1 parent ef23e0f
commit d89ba33
Show file tree

Hide file tree

Showing 7 changed files with 178 additions and 35 deletions.
diff --git a/content/installation/server/docker/_index.md b/content/installation/server/docker/_index.md
@@ -64,6 +64,10 @@ The specific value we need from the output is the line with `key` in it (i.e. `k
 
 ### Step 3: Create a Shared Secret
 
+{{% alert title="Note:" color="primary" %}}
+Skip this step if you are utilizing the [worker registration auth flow](/docs/installation/worker/docker/#worker-registration-and-auth-refresh)
+{{% /alert %}}
+
 Create a shared secret used for authenticating communication between workers and the server.
 
 You can use the [`openssl` command](https://www.openssl.org/) to generate the shared secret:
@@ -74,7 +78,7 @@ $ openssl rand -hex 16
 
 ### Step 4: Create the private key
 
-Create a private key used for minting and validating user and build tokens.
+Create a private key used for minting and validating user, worker auth, and build JWT tokens.
 
 You can also use the [`openssl` command](https://www.openssl.org/) to generate the key.
 
@@ -106,7 +110,6 @@ $ docker run \
   --env=VELA_QUEUE_DRIVER=redis \
   --env=VELA_QUEUE_ADDR=redis://<password>@<hostname>:<port>/<database> \
   --env=VELA_PORT=443 \
-  --env=VELA_SECRET=<shared-secret> \
   --env=VELA_SERVER_PRIVATE_KEY=<private_key> \
   --env=VELA_SCM_CLIENT=<oauth-client-id> \
   --env=VELA_SCM_SECRET=<oauth-client-secret> \
@@ -118,7 +121,11 @@ $ docker run \
   target/vela-server:latest
 ```
 
-{{% alert title="Note:" color="primary" %}}
+{{% alert title="Notes:" color="primary" %}}
+If using the [server-worker trusted symmetric auth method](/docs/installation/worker/docker/#worker-server-trusted-symmetric-token), be sure to add the `VELA_SECRET` env variable:
+```shell
+  --env=VELA_SECRET=<shared_secret>
+```
 For a full list of configuration options, please see the [server reference](/docs/installation/server/reference/).
 {{% /alert %}}
 

diff --git a/content/installation/server/reference/_index.md b/content/installation/server/reference/_index.md
@@ -87,16 +87,6 @@ This variable sets the client secret from the OAuth application created on the S
 
 The variable should be provided as a `string`.
 
-### VELA_SECRET
-
-This variable sets a shared secret with the Vela [worker](/docs/installation/worker/) for authenticating communication between workers and the server.
-
-The variable should be provided as a `string`.
-
-{{% alert title="Note:" color="primary" %}}
-This variable should match [the `VELA_SERVER_SECRET` variable](/docs/installation/worker/reference/#vela_server_secret) provided to the worker.
-{{% /alert %}}
-
 ### VELA_SERVER_PRIVATE_KEY
 
 This variable sets the private key that will be used to sign all JWT tokens within Vela. Please be sure to follow [guidelines](https://www.rfc-editor.org/rfc/rfc2104#section-3) related to generating a private key.
@@ -107,6 +97,18 @@ The variable should be provided as a `string`.
 
 This section contains a list of all variables that can be provided to the server.
 
+### VELA_SECRET
+
+This variable sets a shared secret with the Vela [worker](/docs/installation/worker/) for authenticating communication between workers and the server.
+
+Only necessary to provide if utilizing the [server-worker trusted symmetric worker authentication method](/docs/installation/worker/docker/#worker-server-trusted-symmetric-token).
+
+The variable should be provided as a `string`.
+
+{{% alert title="Note:" color="primary" %}}
+This variable should match [the `VELA_SERVER_SECRET` variable](/docs/installation/worker/reference/#vela_server_secret) provided to the worker.
+{{% /alert %}}
+
 ### VELA_CLONE_IMAGE
 
 This configuration variable is used by the [compiler component](/docs/installation/server/reference/compiler) for the server.
@@ -638,6 +640,34 @@ The variable can be provided as a `string`.
 This variable has a default value of `/account/authenticate`.
 {{% /alert %}}
 
+### VELA_WORKER_AUTH_TOKEN_DURATION
+
+This variable sets the maximum duration of time a Vela auth token for a worker is valid on the server.
+
+The worker auth token is used for authenticating a worker's access to the server to check-in and request build tokens.
+
+The variable can be provided as a `duration` (i.e. `5s`, `10m`).
+
+{{% alert title="Notes:" color="primary" %}}
+This variable should be _longer_ than the [VELA_CHECK_IN](/docs/installation/worker/reference/#vela_check_in) in order to be able to refresh the auth token.
+
+This variable has a default value of `20m`.
+{{% /alert %}}
+
+### VELA_WORKER_REGISTER_TOKEN_DURATION
+
+This variable sets the maximum duration of time a Vela registration token for a worker is valid on the server.
+
+The worker register token is used for onboarding a worker onto the server and beginning its auth refresh routine.
+
+The variable can be provided as a `duration` (i.e. `5s`, `10m`).
+
+{{% alert title="Notes:" color="primary" %}}
+This variable should be relatively short-lived. There is a [CLI Command](/docs/reference/cli/worker/add) to quicken the registration process for admins.
+
+This variable has a default value of `1m`.
+{{% /alert %}}
+
 ### VELA_WORKER_ACTIVE_INTERVAL
 
 This variable sets the interval of time the workers will be considered active. A worker is considered active if it has registered with the server inside the give duration.

diff --git a/content/installation/server/reference/token_manager.md b/content/installation/server/reference/token_manager.md
@@ -14,13 +14,19 @@ The token manager is designed to ensure secure interactions with the server and
 
 The following options are used to configure the component:
 
-| Name                          | Description                                                                                                                     | Required | Default   | Environment Variables                         |
-| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -------- | --------- | --------------------------------------------- |
-| `vela-server-private-key`     | private key used for signing and validating all JWT tokens                                                                      | `true`   | `N/A`     | `VELA_SERVER_PRIVATE_KEY`                     |
-| `user-access-token-duration`  | maximum duration of time a Vela access token for a user is valid on the server                                                  | `true`   | `15m`     | `VELA_USER_ACCESS_TOKEN_DURATION`<br>`USER_ACCESS_TOKEN_DURATION`             |
-| `user-refresh-token-duration` | maximum duration of time a Vela refresh token for a user is valid on the server                                                 | `true`   | `8h`      | `VELA_USER_ACCESS_TOKEN_DURATION`<br>`USER_ACCESS_TOKEN_DURATION`           |
-| `build-token-buffer-duration` | maximum duration of time a Vela build token for a build extends beyond the repo build limit to maintain validity on the server  | `true`   | `5m`      | `VELA_BUILD_TOKEN_BUFFER_DURATION`<br>`BUILD_TOKEN_BUFFER_DURATION`             |
-
-{{% alert title="Note:" color="primary" %}}
+| Name                             | Description                                                                                                                     | Required | Default   | Environment Variables                         |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -------- | --------- | --------------------------------------------- |
+| `vela-server-private-key`        | private key used for signing and validating all JWT tokens                                                                      | `true`   | `N/A`     | `VELA_SERVER_PRIVATE_KEY`                                                   |
+| `user-access-token-duration`     | maximum duration of time a Vela access token for a user is valid on the server                                                  | `true`   | `15m`     | `VELA_USER_ACCESS_TOKEN_DURATION`<br>`USER_ACCESS_TOKEN_DURATION`           |
+| `user-refresh-token-duration`    | maximum duration of time a Vela refresh token for a user is valid on the server                                                 | `true`   | `8h`      | `VELA_USER_ACCESS_TOKEN_DURATION`<br>`USER_ACCESS_TOKEN_DURATION`           |
+| `build-token-buffer-duration`    | maximum duration of time a Vela build token for a build extends beyond the repo build limit to maintain validity on the server  | `true`   | `5m`      | `VELA_BUILD_TOKEN_BUFFER_DURATION`<br>`BUILD_TOKEN_BUFFER_DURATION`         |
+| `worker-auth-token-duration`     | maximum duration of time an auth token for a worker is valid on the server                                                      | `false`*   | `20m`     | `VELA_WORKER_AUTH_TOKEN_DURATION`<br>`WORKER_AUTH_TOKEN_DURATION`           |
+| `worker-register-token-duration` | maximum duration of time a registration token for a worker is valid on the server                                               | `false`*   | `1m`      | `VELA_WORKER_REGISTER_TOKEN_DURATION`<br>`WORKER_REGISTER_TOKEN_DURATION`   |
+
+
+
+{{% alert title="Notes:" color="primary" %}}
+\* `worker-auth-token-duration` and `worker-register-token-duration` are required if you intend to register workers.
+
 For more information on these configuration options, please see the [server reference](/docs/installation/server/reference/).
 {{% /alert %}}
diff --git a/content/installation/worker/docker/_index.md b/content/installation/worker/docker/_index.md
@@ -44,11 +44,17 @@ The `latest` tag will ensure you install the most-recent version of the Vela wor
 To see the full list of available versions, please refer to [the official registry](https://hub.docker.com/r/target/vela-worker).
 {{% /alert %}}
 
-### Step 2: Start the Worker
+### Step 2: Determine Worker Authentication and Start Worker
 
-Start the Vela worker as a [Docker container](https://docs.docker.com/get-started/overview/#containers) that is configured via environment variables.
+Currently, Vela supports two methods of maintaining authentication between the worker and the server. 
 
-You can use the [`docker run` command](https://docs.docker.com/engine/reference/commandline/run/) to start the worker:
+Take care to read through both options to determine which setup makes the most sense for your installation:
+
+##### Worker-Server Trusted Symmetric Token
+
+This authentication method involves using the same secret generated as the `VELA_SECRET` during the [server installation](/docs/installation/server/docker/#step-3-create-a-shared-secret) as the bearer token for all API requests related to check-in and build tokens from the worker to the server.
+
+The token is non-expiring and exists within the container environment. Once the server is running, all that is necessary for a worker to connect to the server and pull builds from the queue is simply starting the worker container:
 
 ```shell
 $ docker run \
@@ -66,10 +72,48 @@ $ docker run \
   target/vela-worker:latest
 ```
 
+The worker must still pass its check-in with the server in order to pull builds from the queue.
+
+##### Worker Registration and Auth Refresh
+
+This authentication method is the more secure of the two options. Rather than using a non-expiring token in the container environment, platform administrators can register workers using their credentials via the Vela CLI. In order to leverage this method, simply do NOT supply the [`VELA_SECRET`](/docs/installation/server/reference/#vela_secret) to the server and do NOT supply the [`VELA_SERVER_SECRET`](/docs/installation/worker/reference/#vela_server_secret) to the worker. 
+
+To start, launch the worker container:
+
+```shell
+$ docker run \
+  --detach=true \
+  --env=VELA_QUEUE_DRIVER=redis \
+  --env=VELA_QUEUE_ADDR=redis://<password>@<hostname>:<port>/<database> \
+  --env=VELA_SERVER_ADDR=https://vela-server.example.com \
+  --env=VELA_WORKER_ADDR=https://vela-worker.example.com \
+  --name=worker \
+  --publish=80:80 \
+  --publish=443:443 \
+  --restart=always \
+  --volume=/var/run/docker.sock:/var/run/docker.sock \
+  target/vela-worker:latest
+```
+
+Once the worker has started, it will be in a paused state until a platform admin registers the worker:
+
+```shell
+$ vela login --api.addr https://vela-server.example.com
+
+$ vela add worker --worker.hostname vela-worker --worker.address https://vela-worker.example.com
+
+worker registered successfully
+```
+
+This process involves the generation of a registration token, which can only be done by platform admins. The quickly expiring registration token is then passed to the worker using an http request to the worker's `/register` endpoint. The worker exchanges this registration token with the server for an auth token. 
+
 {{% alert title="Note:" color="primary" %}}
-For a full list of configuration options, please see the [worker reference](/docs/installation/worker/reference/).
+IMPORTANT: When using this method, ensure that the [`VELA_WORKER_AUTH_TOKEN_DURATION`](/docs/installation/server/reference/#vela_worker_auth_token_duration) configured in the server is _longer_ than the [`VELA_CHECK_IN`](/docs/installation/worker/reference/#vela_check_in) configured in the worker. This ensures that all requests made by the worker are done with a valid token, refreshed at each check-in.
 {{% /alert %}}
 
+Once registered, the worker will continue refreshing its authentication token at the specified check in interval. Workers that lose their connection to the server for long enough for their existing auth
+token to expire will need to be re-registered.
+
 ### Step 3: Verify the Worker Logs
 
 Ensure the worker started up successfully and is running as expected by inspecting the logs.

diff --git a/content/installation/worker/kubernetes/_index.md b/content/installation/worker/kubernetes/_index.md
@@ -32,6 +32,10 @@ This example only shows a subset of all possible configuration options.
 
 You will need to store some env vars in a `Secret`, and the rest can go in a `ConfigMap`.
 
+{{% alert title="Note:" color="primary" %}}
+Determine which worker auth method to use for worker-server communication before writing the `ConfigMap`. Details of the two offerings can be found [here](/docs/installation/worker/docker/#step-2-determine-worker-authentication-and-start-worker).
+{{% /alert %}}
+
 ```yaml
 apiVersion: v1
 kind: Secret
@@ -41,6 +45,7 @@ metadata:
 data:
   # these values are base64 encoded
 
+  # this value should only be specified if using the server-worker trusted symmetric token auth method.
   VELA_SERVER_SECRET: PHNoYXJlZC1zZWNyZXQ+
   # VELA_SERVER_SECRET: <shared-secret>
 

diff --git a/content/installation/worker/reference/_index.md b/content/installation/worker/reference/_index.md
@@ -63,16 +63,6 @@ The variable should be provided as a `string`.
 This variable should match [the `VELA_ADDR` variable](/docs/installation/server/reference/#vela_addr) provided to the server.
 {{% /alert %}}
 
-### VELA_SERVER_SECRET
-
-This variable sets a shared secret for authenticating communication between workers and the server.
-
-The variable should be provided as a `string`.
-
-{{% alert title="Note:" color="primary" %}}
-This variable should match [the `VELA_SECRET` variable](/docs/installation/server/reference/#vela_secret) provided to the server.
-{{% /alert %}}
-
 ### VELA_WORKER_ADDR
 
 This variable sets a fully qualified URL to the Vela [worker](/docs/installation/worker/) address.
@@ -83,6 +73,18 @@ The variable should be provided as a `string`.
 
 This section contains a list of all variables that can be provided to the worker.
 
+### VELA_SERVER_SECRET
+
+This variable sets a shared secret for authenticating communication between workers and the server.
+
+Only necessary to provide if utilizing the [server-worker trusted symmetric worker authentication method](/docs/installation/worker/docker/#worker-server-trusted-symmetric-token).
+
+The variable should be provided as a `string`.
+
+{{% alert title="Note:" color="primary" %}}
+This variable should match [the `VELA_SECRET` variable](/docs/installation/server/reference/#vela_secret) provided to the server.
+{{% /alert %}}
+
 ### VELA_BUILD_LIMIT
 
 This variable sets a number to control the maximum amount of builds that are allowed to run concurrently on the worker.

diff --git a/content/reference/api/admin/worker.md b/content/reference/api/admin/worker.md
@@ -0,0 +1,49 @@
+---
+title: "Worker"
+linkTitle: "Worker"
+description: >
+  Learn how to request a worker registration token as an admin.
+---
+
+## Endpoint
+
+```
+POST  /api/v1/admin/workers/:worker/register-token
+```
+
+## Permissions
+
+COMING SOON!
+
+## Responses
+
+| Status Code | Description                                         |
+| ----------- | --------------------------------------------------- |
+| `200`       | indicates the request has succeeded                 |
+| `401`       | indicates the user does not have proper permissions |
+
+## Sample
+
+{{% alert color="warning" %}}
+This section assumes you already know how to authenticate to the API.
+
+To authenticate to the API, please review the [authentication documentation](/docs/reference/api/authentication/).
+{{% /alert %}}
+
+#### Request
+
+```sh
+curl \
+  -X PUT \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  "http://127.0.0.1:8080/api/v1/admin/workers/worker_1/register-token"
+```
+
+#### Response
+
+```json
+{
+  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ3b3JrZXJfMSIsImlhdCI6MTUxNjIzOTAyMiwiZWF0IjoxNTE2MjQ1MDIyLCJ0b2tlbl90eXBlIjoiV29ya2VyUmVnaXN0ZXIifQ.U2zNa3E8Wwd6ndoVMrwEZ1TWlmMVTZP8-UaShZA1Qpw" 
+}
+```