-
Notifications
You must be signed in to change notification settings - Fork 34
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat(reference): platform settings (#410)
* feat(reference): platform settings * fix: typos --------- Co-authored-by: Kelly Merrick <kelly.merrick@target.com>
- Loading branch information
1 parent
781696f
commit 306bd2e
Showing
7 changed files
with
429 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,14 @@ | ||
| --- | ||
| title: "Settings" | ||
| linkTitle: "Settings" | ||
| description: > | ||
| Learn how to use API endpoints for platform settings. | ||
| --- | ||
|
|
||
| The below endpoints are available to operate on the `settings` resource. | ||
|
|
||
| {{% 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 %}} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,69 @@ | ||
| --- | ||
| title: "Restore" | ||
| linkTitle: "Restore" | ||
| description: > | ||
| Learn how to restore settings to the server environment defaults. | ||
| --- | ||
|
|
||
| ## Endpoint | ||
|
|
||
| ``` | ||
| DELETE /api/v1/admin/settings | ||
| ``` | ||
|
|
||
| ## Permissions | ||
|
|
||
| COMING SOON! | ||
|
|
||
| ## Responses | ||
|
|
||
| | Status Code | Description | | ||
| | ----------- | ---------------------------------------------------------- | | ||
| | `200` | indicates the request has succeeded | | ||
| | `401` | indicates the user does not have proper permissions | | ||
| | `404` | indicates the server was unable to retrieve a resource | | ||
| | `500` | indicates a server failure while processing the request | | ||
|
|
||
| ## 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 DELETE \ | ||
| -H "Authorization: Bearer <token>" \ | ||
| "http://127.0.0.1:8080/api/v1/admin/settings" | ||
| ``` | ||
|
|
||
| #### Response | ||
|
|
||
| ```json | ||
| { | ||
| "id": 1, | ||
| "compiler": { | ||
| "clone_image": "target/vela-git:latest", | ||
| "template_depth": 3, | ||
| "starlark_exec_limit": 7500 | ||
| }, | ||
| "queue": { | ||
| "routes": [ | ||
| "vela" | ||
| ] | ||
| }, | ||
| "repo_allowlist": [ | ||
| "*", | ||
| ], | ||
| "schedule_allowlist": [ | ||
| "github/octocat", | ||
| ], | ||
| "created_at": 1715718878, | ||
| "updated_at": 1715718879, | ||
| "updated_by": "octocat" | ||
| } | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,94 @@ | ||
| --- | ||
| title: "Update" | ||
| linkTitle: "Update" | ||
| description: > | ||
| Learn how to update platform settings. | ||
| --- | ||
|
|
||
| ## Endpoint | ||
|
|
||
| ``` | ||
| PUT /api/v1/admin/settings | ||
| ``` | ||
|
|
||
| ## Permissions | ||
|
|
||
| COMING SOON! | ||
|
|
||
| ## Responses | ||
|
|
||
| | Status Code | Description | | ||
| | ----------- | ---------------------------------------------------------- | | ||
| | `200` | indicates the request has succeeded | | ||
| | `401` | indicates the user does not have proper permissions | | ||
| | `404` | indicates the server was unable to retrieve a resource | | ||
| | `500` | indicates a server failure while processing the request | | ||
|
|
||
| ## 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 %}} | ||
|
|
||
| #### File | ||
|
|
||
| ```json | ||
| { | ||
| "compiler": { | ||
| "clone_image": "target/vela-git:latest", | ||
| "template_depth": 3, | ||
| "starlark_exec_limit": 7500 | ||
| }, | ||
| "queue": { | ||
| "routes": [ | ||
| "vela" | ||
| ] | ||
| }, | ||
| "repo_allowlist": [ | ||
| "*", | ||
| ], | ||
| "schedule_allowlist": [ | ||
| "github/octocat", | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| #### Request | ||
|
|
||
| ```sh | ||
| curl \ | ||
| -X PUT \ | ||
| -H "Authorization: Bearer <token>" \ | ||
| -H "Content-Type: application/json" \ | ||
| -d "@data.json" \ | ||
| "http://127.0.0.1:8080/api/v1/admin/settings" | ||
| ``` | ||
|
|
||
| #### Response | ||
|
|
||
| ```json | ||
| { | ||
| "id": 1, | ||
| "compiler": { | ||
| "clone_image": "target/vela-git:latest", | ||
| "template_depth": 3, | ||
| "starlark_exec_limit": 7500 | ||
| }, | ||
| "queue": { | ||
| "routes": [ | ||
| "vela" | ||
| ] | ||
| }, | ||
| "repo_allowlist": [ | ||
| "*", | ||
| ], | ||
| "schedule_allowlist": [ | ||
| "github/octocat", | ||
| ], | ||
| "created_at": 1715718878, | ||
| "updated_at": 1715718879, | ||
| "updated_by": "octocat" | ||
| } | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,68 @@ | ||
| --- | ||
| title: "View" | ||
| linkTitle: "View" | ||
| description: > | ||
| Learn how to view active platform settings. | ||
| --- | ||
|
|
||
| ## Endpoint | ||
|
|
||
| ``` | ||
| GET /api/v1/admin/settings | ||
| ``` | ||
|
|
||
| ## Permissions | ||
|
|
||
| COMING SOON! | ||
|
|
||
| ## Responses | ||
|
|
||
| | Status Code | Description | | ||
| | ----------- | ---------------------------------------------------------- | | ||
| | `200` | indicates the request has succeeded | | ||
| | `401` | indicates the user does not have proper permissions | | ||
| | `404` | indicates the server was unable to retrieve a resource | | ||
|
|
||
| ## 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 GET \ | ||
| -H "Authorization: Bearer <token>" \ | ||
| "http://127.0.0.1:8080/api/v1/admin/settings" | ||
| ``` | ||
|
|
||
| #### Response | ||
|
|
||
| ```json | ||
| { | ||
| "id": 1, | ||
| "compiler": { | ||
| "clone_image": "target/vela-git:latest", | ||
| "template_depth": 3, | ||
| "starlark_exec_limit": 7500 | ||
| }, | ||
| "queue": { | ||
| "routes": [ | ||
| "vela" | ||
| ] | ||
| }, | ||
| "repo_allowlist": [ | ||
| "*", | ||
| ], | ||
| "schedule_allowlist": [ | ||
| "github/octocat", | ||
| ], | ||
| "created_at": 1715718878, | ||
| "updated_at": 1715718879, | ||
| "updated_by": "octocat" | ||
| } | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,16 @@ | ||
| --- | ||
| title: "Settings" | ||
| linkTitle: "Settings" | ||
| description: > | ||
| Learn how to use CLI commands for platform settings. | ||
| --- | ||
|
|
||
| The below commands are available to operate on the `settings` resource. | ||
|
|
||
| {{% alert color="warning" %}} | ||
| This section assumes you have already installed and setup the CLI. | ||
|
|
||
| To install the CLI, please review the [installation documentation](/docs/reference/cli/install/). | ||
|
|
||
| To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). | ||
| {{% /alert %}} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,110 @@ | ||
| --- | ||
| title: "Update" | ||
| linkTitle: "Update" | ||
| description: > | ||
| Learn how to modify platform settings. | ||
| --- | ||
|
|
||
| ## Command | ||
|
|
||
| ``` | ||
| $ vela update settings <parameters...> <arguments...> | ||
| ``` | ||
|
|
||
| {{% alert color="info" %}} | ||
| For more information, you can run `vela update settings --help`. | ||
| {{% /alert %}} | ||
|
|
||
| ## Parameters | ||
|
|
||
| The following parameters are used to configure the command: | ||
|
|
||
| | Name | Description | Environment Variables | | ||
| | ------------------------------ | ------------------------------------------------------- | ------------------------------------ | | ||
| | `compiler.clone-image` | image used by the compiler to clone repositories | `VELA_COMPILER_CLONE_IMAGE` | | ||
| | `compiler.template-depth` | maximum depth of nested templates | `VELA_COMPILER_TEMPLATE_DEPTH` | | ||
| | `compiler.starlark-exec-limit` | maximum execution limit for Starlark templates | `VELA_COMPILER_STARLARK_EXEC_LIMIT` | | ||
| | `queue.add-route` | add a route to the queue | `VELA_QUEUE_ADD_ROUTES` | | ||
| | `queue.drop-route` | drop a route from the queue | `VELA_QUEUE_DROP_ROUTES` | | ||
| | `add-repo` | name of repository to add to the global allowlist | `VELA_REPO_ALLOWLIST_ADD_REPOS` | | ||
| | `drop-repo` | name of repository to drop from the global allowlist | `VELA_REPO_ALLOWLIST_DROP_REPOS` | | ||
| | `add-schedule` | name of repository to add to the schedules allowlist | `VELA_SCHEDULE_ALLOWLIST_ADD_REPOS` | | ||
| | `drop-schedule` | name of repository to drop from the schedules allowlist | `VELA_SCHEDULE_ALLOWLIST_DROP_REPOS` | | ||
| | `file` | path to a json/yaml file containing settings updates | `VELA_FILE` | | ||
|
|
||
| ## Permissions | ||
|
|
||
| COMING SOON! | ||
|
|
||
| ## Sample | ||
|
|
||
| {{% alert color="warning" %}} | ||
| This section assumes you have already installed and setup the CLI. | ||
|
|
||
| To install the CLI, please review the [installation documentation](/docs/reference/cli/install/). | ||
|
|
||
| To setup the CLI, please review the [authentication documentation](/docs/reference/cli/authentication/). | ||
| {{% /alert %}} | ||
|
|
||
| #### Request | ||
|
|
||
| ```sh | ||
| $ pwd | ||
| ~/github/octocat | ||
| $ vela update settings --compiler.clone-image target/vela-git:abc123 --queue.add-route large | ||
| ``` | ||
|
|
||
| #### Response | ||
|
|
||
| ```yaml | ||
| id: 1 | ||
| compiler: | ||
| clone_image: target/vela-git:latest | ||
| template_depth: 3 | ||
| starlark_exec_limit: 7500 | ||
| queue: | ||
| routes: | ||
| - vela | ||
| repo_allowlist: | ||
| - 'github/octocat' | ||
| schedule_allowlist: | ||
| - '*' | ||
| created_at: 0 | ||
| updated_at: 1715791151 | ||
| updated_by: octocat | ||
| ``` | ||
|
|
||
| ## Advanced | ||
|
|
||
| #### Input From File | ||
|
|
||
| Vela supports updating a settings record from a file using the `@` symbol. | ||
|
|
||
| ```sh | ||
| # Syntax | ||
| vela update settings --file @/path/to/file | ||
|
|
||
| # Example | ||
| vela update settings --file @$HOME/tmp/settings.yml | ||
| ``` | ||
|
|
||
| ##### Single YAML document | ||
|
|
||
| ```yaml | ||
| --- | ||
| platform: | ||
| compiler: | ||
| clone_image: target/vela-git:latest | ||
| template_depth: 3 | ||
| starlark_exec_limit: 7500 | ||
| queue: | ||
| routes: | ||
| - vela | ||
| repo_allowlist: | ||
| - 'github/octocat' | ||
| schedule_allowlist: | ||
| - '*' | ||
| created_at: 0 | ||
| updated_at: 1715791151 | ||
| updated_by: octocat | ||
| ``` |
Oops, something went wrong.