feat: platform settings usage/admin docs (#419)

* feat: platform settings usage/admin docs

* fix: tweaks

* fix: format

* fix: format

* fix: format

* fix: prop

---------

Co-authored-by: Easton Crupper <65553218+ecrupper@users.noreply.github.com>

content/installation/server/reference/_index.md

@@ -11,18 +11,21 @@ description: >
 
 The server is made up of several components, responsible for specific tasks, necessary for the service to operate:
 
-| Name       | Description                                                                                                         |
-| ---------- | ------------------------------------------------------------------------------------------------------------------- |
+| Name       | Description                                                                                                       |
+| ---------- | ----------------------------------------------------------------------------------------------------------------- |
+| `settings` | keeps track of updated runtime properties for the [server](/docs/installation/server/)                            |
 | `compiler` | transforms a [pipeline](/docs/tour/) into an executable workload for the [worker](/docs/installation/worker/)     |
-| `database` | integrates with a database provider for storing application data at rest                                            |
+| `database` | integrates with a database provider for storing application data at rest                                          |
 | `queue`    | integrates with a queue provider for pushing workloads that will be run by a [worker](/docs/installation/worker/) |
-| `secret`   | integrates with a secret provider for storing sensitive application data at rest                                    |
-| `source`   | integrates with a source control management (SCM) provider for authentication and authorization                     |
+| `secret`   | integrates with a secret provider for storing sensitive application data at rest                                  |
+| `source`   | integrates with a source control management (SCM) provider for authentication and authorization                   |
 
 ## Required
 
 This section contains a list of all variables that must be provided to the server.
 
+Some properties can be updated while the server is running using the [settings component](/docs/installation/server/reference/settings).
+
 ### VELA_ADDR
 
 This variable sets a fully qualified URL to the Vela [server](/docs/installation/server/) address.
@@ -93,6 +96,8 @@ The variable should be provided as a `string`.
 
 This section contains a list of all variables that can be provided to the server.
 
+Some properties can be updated while the server is running using the [settings component](/docs/installation/server/reference/settings).
+
 ### VELA_CLONE_IMAGE
 
 This configuration variable is used by the [compiler component](/docs/installation/server/reference/compiler) for the server.
@@ -103,6 +108,8 @@ By default, Vela will use the latest available release of the clone image at the
 
 This variable should be provided as a `string`.
 
+This property can be updated while the server is running using the [settings component](/docs/installation/server/reference/settings).
+
 ### VELA_COMPILER_GITHUB
 
 This configuration variable is used by the [compiler component](/docs/installation/server/reference/compiler/) for the server.
@@ -440,6 +447,22 @@ The variable can be provided as an `integer`.
 This variable has a default value of `3`.
 {{% /alert %}}
 
+This property can be updated while the server is running using the [settings component](/docs/installation/server/reference/settings).
+
+### VELA_COMPILER_STARLARK_EXEC_LIMIT
+
+This configuration variable is used by the [compiler component](/docs/installation/server/reference/compiler) for the server.
+
+This variable sets the starlark execution step limit for compiling starlark pipelines.
+
+The variable can be provided as an `integer`.
+
+{{% alert title="Note:" color="primary" %}}
+This variable has a default value of `7500`.
+{{% /alert %}}
+
+This property can be updated while the server is running using the [settings component](/docs/installation/server/reference/settings).
+
 ### VELA_PORT
 
 This variable sets the port the server API responds on for HTTP requests.
@@ -486,6 +509,8 @@ The variable can be provided as a comma-separated `list` (i.e. `myRoute1,myRoute
 This variable has a default value of `vela`.
 {{% /alert %}}
 
+This property can be updated while the server is running using the [settings component](/docs/installation/server/reference/settings).
+
 ### VELA_QUEUE_PRIVATE_KEY
 
 This variable sets a private key secret for signing queue items that will be opened by the worker's <signing-public-key>.
@@ -508,6 +533,8 @@ The variable can be provided as a comma-separated `list` (i.e. `myOrg1/myRepo1,m
 By default, no repositories are allowed to be enabled. To allow any repository to be enabled, provide a single value of `*`.
 {{% /alert %}}
 
+This property can be updated while the server is running using the [settings component](/docs/installation/server/reference/settings).
+
 ### VELA_SCHEDULE_ALLOWLIST
 
 This variable sets a group of repositories, from the SCM, that can create a schedule for a repo on the server.
@@ -518,6 +545,8 @@ The variable can be provided as a comma-separated `list` (i.e. `myOrg1/myRepo1,m
 By default, no repositories are allowed to create a schedule. To allow any repository to create a schedule, provide a single value of `*`.
 {{% /alert %}}
 
+This property can be updated while the server is running using the [settings component](/docs/installation/server/reference/settings).
+
 ### VELA_SCHEDULE_MINIMUM_FREQUENCY
 
 This variable sets the minimum frequency allowed to be set for a schedule.

content/installation/server/reference/compiler.md

@@ -32,17 +32,18 @@ Some examples of what the modification endpoint can do include, but are not limi
 
 The following options are used to configure the component:
 
-| Name                   | Description                                                                     | Required | Default               | Environment Variables                                   |
-| ---------------------- | ------------------------------------------------------------------------------- | -------- | --------------------- | ------------------------------------------------------- |
-| `clone-image`          | default clone image to use for Vela injected clone step                         | `true`   | `target/vela-git` (1) | `VELA_CLONE_IMAGE`                                      |
-| `github-driver`        | enables using Github or GitHub Enterprise Server as a registry for templates    | `false`  | `false`               | `COMPILER_GITHUB`<br>`VELA_COMPILER_GITHUB`             |
-| `github-url`           | fully qualified url to GitHub or GitHub Enterprise Server for templates         | `false`  | `N/A`                 | `COMPILER_GITHUB_URL`<br>`VELA_COMPILER_GITHUB_URL`     |
-| `github-token`         | token used for authentication when fetching registry templates                  | `false`  | `N/A`                 | `COMPILER_GITHUB_TOKEN`<br>`VELA_COMPILER_GITHUB_TOKEN` |
-| `modification-addr`    | fully qualified url to endpoint for modifying pipelines                         | `false`  | `N/A`                 | `MODIFICATION_ADDR`<br>`VELA_MODIFICATION_ADDR`         |
-| `modification-retries` | number of times to resend failed requests to the modification endpoint          | `false`  | `5`                   | `MODIFICATION_RETRIES`<br>`VELA_MODIFICATION_RETRIES`   |
-| `modification-secret`  | authenticates communication between compiler and the modification endpoint      | `false`  | `N/A`                 | `MODIFICATION_SECRET`<br>`VELA_MODIFICATION_SECRET`     |
-| `modification-timeout` | timeout for requests sent to the modification endpoint                          | `false`  | `8s`                  | `MODIFICATION_TIMEOUT`<br>`VELA_MODIFICATION_TIMEOUT`   |
-| `max-template-depth`   | max depth for calling nested templates during compilation                       | `true`   | `3`                   | `MAX_TEMPLATE_DEPTH`<br>`VELA_MAX_TEMPLATE_DEPTH`       |
+| Name                           | Description                                                                  | Required | Default               | Environment Variables                                                 |
+| ------------------------------ | ---------------------------------------------------------------------------- | -------- | --------------------- | --------------------------------------------------------------------- |
+| `clone-image`                  | default clone image to use for Vela injected clone step                      | `true`   | `target/vela-git` (1) | `VELA_CLONE_IMAGE`                                                    |
+| `github-driver`                | enables using Github or GitHub Enterprise Server as a registry for templates | `false`  | `false`               | `COMPILER_GITHUB`<br>`VELA_COMPILER_GITHUB`                           |
+| `github-url`                   | fully qualified url to GitHub or GitHub Enterprise Server for templates      | `false`  | `N/A`                 | `COMPILER_GITHUB_URL`<br>`VELA_COMPILER_GITHUB_URL`                   |
+| `github-token`                 | token used for authentication when fetching registry templates               | `false`  | `N/A`                 | `COMPILER_GITHUB_TOKEN`<br>`VELA_COMPILER_GITHUB_TOKEN`               |
+| `modification-addr`            | fully qualified url to endpoint for modifying pipelines                      | `false`  | `N/A`                 | `MODIFICATION_ADDR`<br>`VELA_MODIFICATION_ADDR`                       |
+| `modification-retries`         | number of times to resend failed requests to the modification endpoint       | `false`  | `5`                   | `MODIFICATION_RETRIES`<br>`VELA_MODIFICATION_RETRIES`                 |
+| `modification-secret`          | authenticates communication between compiler and the modification endpoint   | `false`  | `N/A`                 | `MODIFICATION_SECRET`<br>`VELA_MODIFICATION_SECRET`                   |
+| `modification-timeout`         | timeout for requests sent to the modification endpoint                       | `false`  | `8s`                  | `MODIFICATION_TIMEOUT`<br>`VELA_MODIFICATION_TIMEOUT`                 |
+| `max-template-depth`           | max depth for calling nested templates during compilation                    | `true`   | `3`                   | `MAX_TEMPLATE_DEPTH`<br>`VELA_MAX_TEMPLATE_DEPTH`                     |
+| `compiler-starlark-exec-limit` | execution step limit for compiling starlark pipelines                        | `true`   | `7500`                | `COMPILER_STARLARK_EXEC_LIMIT`<br>`VELA_COMPILER_STARLARK_EXEC_LIMIT` |
 
 _(1) this will be the latest available, tagged release of `target/vela-git` at the time the server component is released_
 

content/installation/server/reference/settings.md

@@ -0,0 +1,60 @@
+---
+title: "Settings"
+linkTitle: "Settings"
+weight: 1
+description: >
+  This section contains information on using dynamic platform settings for the Vela server.
+---
+
+Platform Administrators can update certain properties during runtime to change how the platform behaves in real time.
+
+The following properties are available to be updated:
+
+* [`VELA_REPO_ALLOWLIST`](/docs/installation/server/reference#vela_repo_allowlist)
+* [`VELA_SCHEDULE_ALLOWLIST`](/docs/installation/server/reference#vela_schedule_allowlist)
+* [`VELA_MAX_TEMPLATE_DEPTH`](/docs/installation/server/reference#vela_max_template_depth)
+* [`VELA_COMPILER_STARLARK_EXEC_LIMIT`](/docs/installation/server/reference#vela_compiler_starlark_exec_limit)
+* [`VELA_CLONE_IMAGE`](/docs/installation/server/reference#vela_clone_image)
+
+
+## Configuration
+
+The following options are used to configure the component:
+
+| Name                        | Description                                              | Required | Default | Environment Variables                                                       |
+| --------------------------- | -------------------------------------------------------- | -------- | ------- | --------------------------------------------------------------------------- |
+| `settings-refresh-interval` | the interval at which the server syncs with the database | `true`   | `5s`    | `VELA_PLATFORM_SETTINGS_REFRESH_INTERVAL`, `VELA_SETTINGS_REFRESH_INTERVAL` |
+
+{{% alert title="Note:" color="primary" %}}
+For more information on how the runtime properties are consumed, please see the [server reference](/docs/installation/server/reference/).
+{{% /alert %}}
+
+## Permissions
+
+This functionality only exists for [Platform Administrators](/docs/usage/roles/).
+
+## Usage
+
+### Initializing
+
+The server will ensure shared settings are first initialized using the variables provided in the environment. For more information on how the runtime properties are configured, please see the [server reference](/docs/installation/server/reference/). 
+
+On subsequent server startups, the properties controlled by the `settings` component will be retrieved from the database.
+
+If the database settings record is deleted then the server will fail. On the next startup the server will re-initialize the settings record using the values provided in the environment.
+
+### Server Synchronization
+
+The server will keep its own `settings` in sync with the database according to the `settings-refresh-interval` set in the environment.
+
+### Viewing and Updating Properties
+
+To view or update settings via the user interface, log into your Vela instance and click the `site admin` link in the top right corner or navigate to `https://vela-server.example.com/admin/settings`.
+
+Check the [CLI docs](/docs/reference/cli/settings) for instructions on modifying runtime properties via the command line.
+
+Updated properties will propagate to all server instances depending on the `settings-refresh-interval` set in the environment on startup.
+
+### Restoring Default Properties
+
+The [`DELETE  /api/v1/admin/settings`](/docs/reference/api/admin/settings/restore) API endpoint can be used to "restore" the server to its original environment-provided configurations. Acting as a way for platform admins to undo any current modifications to the platform without restarting or modifying the database.

content/templates/tutorials/starlark/functions.md

@@ -32,6 +32,8 @@ twice("two")            # "twotwo"
 
 > Finally, there may be an optional parameter name preceded by **. This is called the keyword arguments parameter, and accumulates in a dictionary any surplus name=value arguments that do not match a prior parameter.
 
+The limitation on _how many_ steps can be used is determined by the `VELA_COMPILER_STARLARK_EXEC_LIMIT` flag set by platform administrators.
+
 ## Sample
 
 Let's take a look at using a function within a template: