diff --git a/docs/reference/installation/server/compiler.md b/docs/reference/installation/server/compiler.md index bdfb211..7291ef2 100644 --- a/docs/reference/installation/server/compiler.md +++ b/docs/reference/installation/server/compiler.md @@ -33,18 +33,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`\`VELA_COMPILER_GITHUB` | -| `github-url` | fully qualified url to GitHub or GitHub Enterprise Server for templates | `false` | `N/A` | `COMPILER_GITHUB_URL`\`VELA_COMPILER_GITHUB_URL` | -| `github-token` | token used for authentication when fetching registry templates | `false` | `N/A` | `COMPILER_GITHUB_TOKEN`\`VELA_COMPILER_GITHUB_TOKEN` | -| `modification-addr` | fully qualified url to endpoint for modifying pipelines | `false` | `N/A` | `MODIFICATION_ADDR`\`VELA_MODIFICATION_ADDR` | -| `modification-retries` | number of times to resend failed requests to the modification endpoint | `false` | `5` | `MODIFICATION_RETRIES`\`VELA_MODIFICATION_RETRIES` | -| `modification-secret` | authenticates communication between compiler and the modification endpoint | `false` | `N/A` | `MODIFICATION_SECRET`\`VELA_MODIFICATION_SECRET` | -| `modification-timeout` | timeout for requests sent to the modification endpoint | `false` | `8s` | `MODIFICATION_TIMEOUT`\`VELA_MODIFICATION_TIMEOUT` | -| `max-template-depth` | max depth for calling nested templates during compilation | `true` | `3` | `MAX_TEMPLATE_DEPTH`\`VELA_MAX_TEMPLATE_DEPTH` | -| `compiler-starlark-exec-limit` | execution step limit for compiling starlark pipelines | `true` | `7500` | `COMPILER_STARLARK_EXEC_LIMIT`\`VELA_COMPILER_STARLARK_EXEC_LIMIT` | +| 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`,`VELA_COMPILER_GITHUB` | +| `github-url` | fully qualified url to GitHub or GitHub Enterprise Server for templates | `false` | `N/A` | `COMPILER_GITHUB_URL`,`VELA_COMPILER_GITHUB_URL` | +| `github-token` | token used for authentication when fetching registry templates | `false` | `N/A` | `COMPILER_GITHUB_TOKEN`,`VELA_COMPILER_GITHUB_TOKEN` | +| `modification-addr` | fully qualified url to endpoint for modifying pipelines | `false` | `N/A` | `MODIFICATION_ADDR`,`VELA_MODIFICATION_ADDR` | +| `modification-retries` | number of times to resend failed requests to the modification endpoint | `false` | `5` | `MODIFICATION_RETRIES`,`VELA_MODIFICATION_RETRIES` | +| `modification-secret` | authenticates communication between compiler and the modification endpoint | `false` | `N/A` | `MODIFICATION_SECRET`,`VELA_MODIFICATION_SECRET` | +| `modification-timeout` | timeout for requests sent to the modification endpoint | `false` | `8s` | `MODIFICATION_TIMEOUT`,`VELA_MODIFICATION_TIMEOUT` | +| `max-template-depth` | max depth for calling nested templates during compilation | `true` | `3` | `MAX_TEMPLATE_DEPTH`,`VELA_MAX_TEMPLATE_DEPTH` | +| `compiler-starlark-exec-limit` | execution step limit for compiling starlark pipelines | `true` | `7500` | `COMPILER_STARLARK_EXEC_LIMIT`,`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_ diff --git a/docs/reference/installation/server/database.md b/docs/reference/installation/server/database.md index 587cdad..de96ec0 100644 --- a/docs/reference/installation/server/database.md +++ b/docs/reference/installation/server/database.md @@ -20,20 +20,23 @@ Any sensitive data stored in the database will be encrypted using the [Advanced The following options are used to configure the component: -| Name | Description | Required | Default | Environment Variables | -| ----------------------------- | ---------------------------------------------------------------- | -------- | ------------- | --------------------------------------------------------------------- | -| `database.addr` | full connection string to the database | `true` | `sqlite3` | `DATABASE_ADDR`\`VELA_DATABASE_ADDR` | -| `database.driver` | type of client to control and operate the database | `true` | `vela.sqlite` | `DATABASE_DRIVER`\`VELA_DATABASE_DRIVER` | -| `database.compression.level` | level of compression for logs stored in the database | `true` | `3` | `DATABASE_COMPRESSION_LEVEL`\`VELA_DATABASE_COMPRESSION_LEVEL` | -| `database.connection.idle` | maximum number of idle connections to the database | `true` | `2` | `DATABASE_CONNECTION_IDLE`\`VELA_DATABASE_CONNECTION_IDLE` | -| `database.connection.life` | duration of time a connection is reusable | `true` | `30m` | `DATABASE_CONNECTION_LIFE`\`VELA_DATABASE_CONNECTION_LIFE` | -| `database.connection.open` | maximum number of open connections to the database | `true` | `0` | `DATABASE_CONNECTION_OPEN`\`VELA_DATABASE_CONNECTION_OPEN` | -| `database.encryption.key` | AES-256 key for encrypting/decrypting values in the database | `true` | `N/A` | `DATABASE_ENCRYPTION_KEY`\`VELA_DATABASE_ENCRYPTION_KEY` | -| `database.skip_creation` | skips the creation of tables and indexes in the database | `false` | `false` | `DATABASE_SKIP_CREATION`\`VELA_DATABASE_SKIP_CREATION` | -| `database.log.level` | log level for database | `false` | `warn` | `DATABASE_LOG_LEVEL` \ `VELA_DATABASE_LOG_LEVEL` | -| `database.log.show_sql` | show sql query in logs | `false` | `false` | `DATABASE_LOG_SHOW_SQL` \ `VELA_DATABASE_LOG_SHOW_SQL` | -| `database.log.skip_notfound` | skip logging not found errors | `false` | `true` | `DATABASE_LOG_SKIP_NOTFOUND` \ `VELA_DATABASE_LOG_SKIP_NOTFOUND` | -| `database.log.slow_threshold` | queries higher than this value are considered slow and logged | `false` | `200ms` | `DATABASE_LOG_SLOW_THRESHOLD` \ `VELA_DATABASE_LOG_SLOW_THRESHOLD` | +| Name | Description | Required | Default | Environment Variables | +| -------------------------------- | ------------------------------------------------------------------ | -------- | ------------- | ------------------------------------------------------------------------ | +| `database.addr` | full connection string / DSN to the database | `true` | `vela.sqlite` | `DATABASE_ADDR`,`VELA_DATABASE_ADDR` | +| `database.driver` | type of client to control and operate the database | `true` | `sqlite3` | `DATABASE_DRIVER`,`VELA_DATABASE_DRIVER` | +| `database.compression.level` | level of compression for logs stored in the database | `true` | `3` | `DATABASE_COMPRESSION_LEVEL`,`VELA_DATABASE_COMPRESSION_LEVEL` | +| `database.connection.idle` | maximum number of idle connections to the database | `true` | `2` | `DATABASE_CONNECTION_IDLE`,`VELA_DATABASE_CONNECTION_IDLE` | +| `database.connection.life` | duration of time a connection is reusable | `true` | `30m` | `DATABASE_CONNECTION_LIFE`,`VELA_DATABASE_CONNECTION_LIFE` | +| `database.connection.open` | maximum number of open connections to the database | `true` | `0` | `DATABASE_CONNECTION_OPEN`,`VELA_DATABASE_CONNECTION_OPEN` | +| `database.encryption.key` | AES-256 key for encrypting/decrypting values in the database | `true` | `N/A` | `DATABASE_ENCRYPTION_KEY`,`VELA_DATABASE_ENCRYPTION_KEY` | +| `database.skip_creation` | skips the creation of tables and indexes in the database | `false` | `false` | `DATABASE_SKIP_CREATION`,`VELA_DATABASE_SKIP_CREATION` | +| `database.log.level` | log level for database | `false` | `warn` | `DATABASE_LOG_LEVEL` \ `VELA_DATABASE_LOG_LEVEL` | +| `database.log.show_sql` | show sql query in logs | `false` | `false` | `DATABASE_LOG_SHOW_SQL` \ `VELA_DATABASE_LOG_SHOW_SQL` | +| `database.log.skip_notfound` | skip logging not found errors | `false` | `true` | `DATABASE_LOG_SKIP_NOTFOUND` \ `VELA_DATABASE_LOG_SKIP_NOTFOUND` | +| `database.log.slow_threshold` | queries higher than this value are considered slow and logged | `false` | `200ms` | `DATABASE_LOG_SLOW_THRESHOLD` \ `VELA_DATABASE_LOG_SLOW_THRESHOLD` | +| `database.log.partitioned` | enables partition-aware log cleanup for partitioned log tables | `false` | `false` | `DATABASE_LOG_PARTITIONED` \ `VELA_DATABASE_LOG_PARTITIONED` | +| `database.log.partition_pattern` | naming pattern for log table partitions (e.g. `logs_%`, `logs_y%`) | `false` | `logs_%` | `DATABASE_LOG_PARTITION_PATTERN` \ `VELA_DATABASE_LOG_PARTITION_PATTERN` | +| `database.log.partition_schema` | database schema containing log table partitions | `false` | `public` | `DATABASE_LOG_PARTITION_SCHEMA` \ `VELA_DATABASE_LOG_PARTITION_SCHEMA` | :::note For more information on these configuration options, please see the [server reference](/docs/reference/installation/server/server.md). diff --git a/docs/reference/installation/server/queue.md b/docs/reference/installation/server/queue.md index c498e98..38b0f44 100644 --- a/docs/reference/installation/server/queue.md +++ b/docs/reference/installation/server/queue.md @@ -16,9 +16,9 @@ Workloads published to the queue are managed with a [first in, first out (FIFO)] The following options are used to configure the component: -| Name | Description | Required | Default | Environment Variables | -| ------------------- | ------------------------------------------------------------- | -------- | ---------- | ----------------------------------------------- | -| `queue.addr` | full connection string to the queue | `true` | `N/A` | `QUEUE_ADDR`\`VELA_QUEUE_ADDR` | +| Name | Description | Required | Default | Environment Variables | +| ------------------- | ------------------------------------------------------------- | -------- | ---------- | -------------------------------------------- | +| `queue.addr` | full connection string to the queue | `true` | `N/A` | `QUEUE_ADDR`/`VELA_QUEUE_ADDR` | | `queue.cluster` | configures the client for a queue cluster | `false` | `false` | `QUEUE_CLUSTER`\`VELA_QUEUE_CLUSTER` | | `queue.driver` | type of client to control and operate queue | `true` | `N/A` | `QUEUE_DRIVER`\`VELA_QUEUE_DRIVER` | | `queue.pop.timeout` | timeout for requests that pop items off the queue | `true` | `60s` | `QUEUE_POP_TIMEOUT`\`VELA_QUEUE_POP_TIMEOUT` | diff --git a/docs/reference/installation/server/scm.md b/docs/reference/installation/server/scm.md index 0ff523c..954552c 100644 --- a/docs/reference/installation/server/scm.md +++ b/docs/reference/installation/server/scm.md @@ -16,15 +16,24 @@ The SCM system is used by Vela for both authentication and authorization of inte The following options are used to configure the component: -| Name | Description | Required | Default | Environment Variables | -| ------------------ | --------------------------------------------------------------- | -------- | -------------------------------------------------------- | --------------------------------------------- | -| `scm.addr` | fully qualified url for the SCM | `true` | `https://github.com` | `SCM_ADDR`\`VELA_SCM_ADDR` | -| `scm.client` | client ID from the generated OAuth application on the SCM | `true` | `N/A` | `SCM_CLIENT`\`VELA_SCM_CLIENT` | -| `scm.context` | message to set in commit status on the SCM | `true` | `continuous-integration/vela` | `SCM_CONTEXT`\`VELA_SCM_CONTEXT` | -| `scm.driver` | type of client to control and operate SCM | `true` | `github` | `SCM_DRIVER`\`VELA_SCM_DRIVER` | -| `scm.scopes` | permission scopes to apply for the OAuth credentials on the SCM | `true` | `[ repo, repo:status, user:email, read:user, read:org ]` | `SCM_SCOPES`\`VELA_SCM_SCOPES` | -| `scm.secret` | client secret from the generated OAuth application on the SCM | `true` | `N/A` | `SCM_SECRET`\`VELA_SCM_SECRET` | -| `scm.webhook.addr` | url for webhooks on the SCM to send requests to | `false` | the address of the Vela server (`$VELA_ADDR`) | `SCM_WEBHOOK_ADDR`\`VELA_SCM_WEBHOOK_ADDR` | +| Name | Description | Required | Default | Environment Variables | +| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------- | ---------------------------------------------------------- | +| `scm.addr` | fully qualified url for the SCM | `true` | `https://github.com` | `SCM_ADDR`,`VELA_SCM_ADDR` | +| `scm.client` | client ID from the generated OAuth application on the SCM | `true` | `N/A` | `SCM_CLIENT`,`VELA_SCM_CLIENT` | +| `scm.context` | message to set in commit status on the SCM | `true` | `continuous-integration/vela` | `SCM_CONTEXT`,`VELA_SCM_CONTEXT` | +| `scm.driver` | type of client to control and operate SCM | `true` | `github` | `SCM_DRIVER`,`VELA_SCM_DRIVER` | +| `scm.scopes` | permission scopes to apply for the OAuth credentials on the SCM | `true` | `[ repo, repo:status, user:email, read:user, read:org ]` | `SCM_SCOPES`,`VELA_SCM_SCOPES` | +| `scm.secret` | client secret from the generated OAuth application on the SCM | `true` | `N/A` | `SCM_SECRET`,`VELA_SCM_SECRET` | +| `scm.webhook.addr` | url for webhooks on the SCM to send requests to (alternative/public address; defaults to `$VELA_ADDR`) | `false` | the address of the Vela server (`$VELA_ADDR`) | `SCM_WEBHOOK_ADDR`,`VELA_SCM_WEBHOOK_ADDR` | +| `vela-disable-webhook-validation` | disables validation of inbound webhooks (ONLY for local development/testing) | `false` | `false` | `VELA_DISABLE_WEBHOOK_VALIDATION` | +| `scm.app.id` | ID for the SCM App integration (GitHub App) | `false` | `N/A` | `SCM_APP_ID`,`VELA_SCM_APP_ID` | +| `scm.app.private-key` | base64 encoded private key value for SCM App integration (one of this OR `scm.app.private-key.path` required when `scm.app.id` set) | `false` | `N/A` | `SCM_APP_PRIVATE_KEY`,`VELA_SCM_APP_PRIVATE_KEY` | +| `scm.app.private-key.path` | filesystem path to private key for SCM App integration (alternative to `scm.app.private-key`) | `false` | `N/A` | `SCM_APP_PRIVATE_KEY_PATH`,`VELA_SCM_APP_PRIVATE_KEY_PATH` | +| `scm.app.webhook-secret` | webhook HMAC secret for SCM App integration (required when `scm.app.id` set and webhook validation enabled) | `false` | `N/A` | `SCM_APP_WEBHOOK_SECRET`,`VELA_SCM_APP_WEBHOOK_SECRET` | +| `scm.app.permissions` | allowed installation token permissions for SCM App integration | `false` | `[ contents:read, checks:write ]` | `SCM_APP_PERMISSIONS`,`VELA_SCM_APP_PERMISSIONS` | +| `scm.repo.roles-map` | map of SCM repository roles -> Vela permissions | `false` | `{ admin: admin, write: write, maintain: write, triage: read, read: read }` | `SCM_REPO_ROLES_MAP`,`VELA_SCM_REPO_ROLES_MAP` | +| `scm.org.roles-map` | map of SCM organization roles -> Vela permissions | `false` | `{ admin: admin, member: read }` | `SCM_ORG_ROLES_MAP`,`VELA_SCM_ORG_ROLES_MAP` | +| `scm.team.roles-map` | map of SCM team roles -> Vela permissions | `false` | `{ maintainer: admin, member: read }` | `SCM_TEAM_ROLES_MAP`,`VELA_SCM_TEAM_ROLES_MAP` | :::note For more information on these configuration options, please see the [server reference](/docs/reference/installation/server/server.md). diff --git a/docs/reference/installation/server/secret.md b/docs/reference/installation/server/secret.md index 74f3ae6..9e3327d 100644 --- a/docs/reference/installation/server/secret.md +++ b/docs/reference/installation/server/secret.md @@ -20,16 +20,16 @@ Any sensitive data stored in the database will be encrypted using the [Advanced The following options are used to configure the component: -| Name | Description | Required | Default | Environment Variables | -| -------------------------- | ---------------------------------------------------------------------------- | -------- | ------- | ------------------------------------------------------------- | -| `secret.vault.addr` | fully qualified url to the HashiCorp Vault instance | `true` | `N/A` | `SECRET_VAULT_ADDR`\`VELA_SECRET_VAULT_ADDR` | -| `secret.vault.auth-method` | authentication method used to obtain token from the HashiCorp Vault instance | `false` | `N/A` | `SECRET_VAULT_AUTH_METHOD`\`VELA_SECRET_VAULT_AUTH_METHOD` | -| `secret.vault.aws-role` | HashiCorp Vault role used to connect to the auth/aws/login endpoint | `false` | `N/A` | `SECRET_VAULT_AWS_ROLE`\`VELA_SECRET_VAULT_AWS_ROLE` | -| `secret.vault.driver` | enables HashiCorp Vault as a secret engine | `true` | `false` | `SECRET_VAULT`\`VELA_SECRET_VAULT` | -| `secret.vault.prefix` | prefix for k/v secrets in the HashiCorp Vault instance | `false` | `N/A` | `SECRET_VAULT_PREFIX`\`VELA_SECRET_VAULT_PREFIX` | -| `secret.vault.renewal` | frequency to renew the token for the HashiCorp Vault instance | `false` | `30m` | `SECRET_VAULT_RENEWAL`\`VELA_SECRET_VAULT_RENEWAL` | -| `secret.vault.token` | token required to access the HashiCorp Vault instance | `true` | `N/A` | `SECRET_VAULT_TOKEN`\`VELA_SECRET_VAULT_TOKEN` | -| `secret.vault.version` | version for the k/v backend for the HashiCorp Vault instance | `true` | `2` | `SECRET_VAULT_VERSION`\`VELA_SECRET_VAULT_VERSION` | +| Name | Description | Required | Default | Environment Variables | +| -------------------------- | ---------------------------------------------------------------------------- | -------- | ------- | ---------------------------------------------------------- | +| `secret.vault.addr` | fully qualified url to the HashiCorp Vault instance | `true` | `N/A` | `SECRET_VAULT_ADDR`,`VELA_SECRET_VAULT_ADDR` | +| `secret.vault.auth-method` | authentication method used to obtain token from the HashiCorp Vault instance | `false` | `N/A` | `SECRET_VAULT_AUTH_METHOD`,`VELA_SECRET_VAULT_AUTH_METHOD` | +| `secret.vault.aws-role` | HashiCorp Vault role used to connect to the auth/aws/login endpoint | `false` | `N/A` | `SECRET_VAULT_AWS_ROLE`,`VELA_SECRET_VAULT_AWS_ROLE` | +| `secret.vault.driver` | enables HashiCorp Vault as a secret engine | `true` | `false` | `SECRET_VAULT`,`VELA_SECRET_VAULT` | +| `secret.vault.prefix` | prefix for k/v secrets in the HashiCorp Vault instance | `false` | `N/A` | `SECRET_VAULT_PREFIX`,`VELA_SECRET_VAULT_PREFIX` | +| `secret.vault.renewal` | frequency to renew the token for the HashiCorp Vault instance | `false` | `30m` | `SECRET_VAULT_RENEWAL`,`VELA_SECRET_VAULT_RENEWAL` | +| `secret.vault.token` | token required to access the HashiCorp Vault instance | `true` | `N/A` | `SECRET_VAULT_TOKEN`,`VELA_SECRET_VAULT_TOKEN` | +| `secret.vault.version` | version for the k/v backend for the HashiCorp Vault instance | `true` | `2` | `SECRET_VAULT_VERSION`,`VELA_SECRET_VAULT_VERSION` | :::note For more information on these configuration options, please see the [server reference](/docs/reference/installation/server/server.md). diff --git a/docs/reference/installation/server/server.md b/docs/reference/installation/server/server.md index 30153bf..4723817 100644 --- a/docs/reference/installation/server/server.md +++ b/docs/reference/installation/server/server.md @@ -11,15 +11,15 @@ description: > The server is made up of several components, responsible for specific tasks, necessary for the service to operate: -| Name | Description | -| ---------- | ----------------------------------------------------------------------------------------------------------------- | -| `settings` | keeps track of updated runtime properties for the [server](/docs/installation/server/server.md) | -| `compiler` | transforms a [pipeline](/docs/usage/tour/tour.md) into an executable workload for the [worker](/docs/installation/worker/worker.md) | -| `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/worker.md) | -| `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 | -| `tracing` | implements OpenTelemetry tracing instrumentation for the [server](/docs/installation/server/server.md) | +| Name | Description | +| ---------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| `settings` | keeps track of updated runtime properties for the [server](/docs/installation/server/server.md) | +| `compiler` | transforms a [pipeline](/docs/usage/tour/tour.md) into an executable workload for the [worker](/docs/installation/worker/worker.md) | +| `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/worker.md) | +| `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 | +| `tracing` | implements OpenTelemetry tracing instrumentation for the [server](/docs/installation/server/server.md) | ## Required @@ -111,6 +111,16 @@ This variable should be provided as a `string`. This property can be updated while the server is running using the [settings component](/docs/reference/installation/server/settings.md). +### VELA_CORS_ALLOW_ORIGINS + +This variable sets the list of origins a cross-domain request can be executed from for the server API. + +The variable can be provided as a comma-separated `list` (i.e. `https://example.com,https://sub.example.com`). + +:::note +This variable has no default value. When unset, CORS is effectively disabled (no origins explicitly allowed). +::: + ### VELA_COMPILER_GITHUB This configuration variable is used by the [compiler component](/docs/reference/installation/server/compiler.md) for the server. @@ -336,6 +346,16 @@ The variable can be provided as an `integer`. This variable has a default value of `30`. ::: +### VELA_DEFAULT_APPROVAL_TIMEOUT + +This variable sets the default duration (in days) that a pending approval will remain valid before expiring. + +The variable can be provided as an `integer` (days). + +:::note +This variable has a default value that matches the server constant `ApprovalTimeoutDefault` (currently `30`). +::: + ### VELA_DEFAULT_REPO_EVENTS This variable sets the default active events for newly activated repositories. @@ -346,6 +366,28 @@ The variable can be provided as a comma-separated `list` (i.e. `push,tag,deploym By default, the `push` event is enabled. Valid values are: `push`, `pull_request`, `tag`, `deployment`, and `comment`. ::: +### VELA_DEFAULT_REPO_EVENTS_MASK + +This variable sets the default event bitmask applied to newly activated repositories. It can be used instead of, or in conjunction with, `VELA_DEFAULT_REPO_EVENTS` for more granular internal enablement. + +The variable can be provided as an `integer` (bitmask). + +:::note +This variable has no default value. When unset, the mask derived from `VELA_DEFAULT_REPO_EVENTS` is used. +::: + +### VELA_DEFAULT_REPO_APPROVE_BUILD + +This variable sets the default approval strategy for builds triggered from outside contributors on newly activated repositories. + +The variable can be provided as a `string`. + +:::note +Valid values are: `fork-always`, `fork-no-write`, `first-time`, `never`. + +This variable has a default value of `fork-always`. +::: + ### VELA_DISABLE_WEBHOOK_VALIDATION This variable disables validation of webhooks sent by the SCM to the server. @@ -370,6 +412,16 @@ This variable should only be used for local development. This variable has a default value of `true`. ::: +### VELA_LOG_LEVEL + +This variable sets the log level for the server process. + +The variable can be provided as a `string` (trace, debug, info, warn, error, fatal, panic). + +:::note +This variable has a default value of `info`. +::: + ### VELA_LOG_FORMATTER This variable sets whether the logging formatter used for structured server logs is a standard JSON logger, or a custom Elasticsearch Common Schema (ECS) compatible JSON formatter. @@ -396,6 +448,16 @@ This variable has a default value of `30`. This variable should match [the `VELA_MAX_BUILD_LIMIT` variable](/reference/installation/ui/#vela_max_build_limit) provided to the UI. ::: +### VELA_MAX_DASHBOARD_REPOS + +This variable sets the maximum number of repositories that can be assigned to a single dashboard resource. + +The variable can be provided as an `integer`. + +:::note +This variable has a default value of `10`. +::: + ### VELA_MODIFICATION_ADDR This configuration variable is used by the [compiler component](/docs/reference/installation/server/compiler.md) for the server. @@ -524,6 +586,16 @@ This variable sets a public key secret for opening queue items that have been si The variable should be provided as a base64 encoded `string`. +### VELA_QUEUE_RESTART_LIMIT + +This variable sets the maximum queue size (in pending builds) before queued (pending) builds are no longer allowed to be restarted. Setting to `0` disables enforcement. + +The variable can be provided as an `integer`. + +:::note +This variable has a default value of `30`. +::: + ### VELA_REPO_ALLOWLIST This variable sets a group of repositories, from the SCM, that can be enabled on the server. @@ -558,6 +630,16 @@ The variable can be provided as a `duration` (i.e. `5s`, `10m`). This variable has a default value of `1h`. ::: +### VELA_SCHEDULE_INTERVAL + +This variable sets the interval at which schedules will be processed by the server to trigger builds. + +The variable can be provided as a `duration` (i.e. `5s`, `10m`). + +:::note +This variable has a default value of `5m`. +::: + ### VELA_SCM_ADDR This configuration variable is used by the [SCM component](/docs/reference/installation/server/scm.md) for the server. @@ -740,6 +822,26 @@ The variable can be provided as a `duration` (i.e. `5s`, `10m`). This variable has a default value of `8h`. ::: +### VELA_OPEN_ID_TOKEN_DURATION + +This variable sets the maximum duration of time an OpenID token requested during a build is valid. It should be short-lived for security. + +The variable can be provided as a `duration` (i.e. `5s`, `10m`). + +:::note +This variable has a default value of `5m`. +::: + +### VELA_OPEN_ID_ISSUER + +This variable sets the issuer URL placed in OpenID tokens requested during a build. + +The variable can be provided as a `string` (fully qualified URL). + +:::note +This variable has no default value. +::: + ### VELA_BUILD_TOKEN_BUFFER_DURATION This variable sets the maximum duration of time a Vela build token for a build extends beyond the repo build limit to maintain validity on the server. @@ -808,6 +910,17 @@ This variable has a default value of `5m`.\ The value should coordinate with the [`VELA_CHECK_IN`](/reference/installation/worker/#vela_check_in) setting provided to the [worker](/docs/installation/worker/worker.md). ::: +### VELA_PLATFORM_SETTINGS_REFRESH_INTERVAL + +This variable sets the interval at which dynamically updatable platform settings are refreshed from persistent storage. + +The variable can be provided as a `duration` (i.e. `5s`, `10m`). + +:::note +This variable has a default value of `5s`. +It is an alias of `VELA_SETTINGS_REFRESH_INTERVAL`. +::: + ### VELA_OTEL_TRACING_ENABLE This variable enables [OpenTelemetry tracing](https://opentelemetry.io/docs/concepts/signals/traces/) for the Vela server. You must provide `VELA_OTEL_EXPORTER_OTLP_ENDPOINT` **when tracing is enabled**. diff --git a/docs/reference/installation/server/settings.md b/docs/reference/installation/server/settings.md index 2b80c92..202a89f 100644 --- a/docs/reference/installation/server/settings.md +++ b/docs/reference/installation/server/settings.md @@ -15,6 +15,8 @@ The following properties are available to be updated: * [`VELA_MAX_TEMPLATE_DEPTH`](/reference/installation/server/#vela_max_template_depth) * [`VELA_COMPILER_STARLARK_EXEC_LIMIT`](/reference/installation/server/#vela_compiler_starlark_exec_limit) * [`VELA_CLONE_IMAGE`](/reference/installation/server/#vela_clone_image) +* [`VELA_MAX_DASHBOARD_REPOS`](/reference/installation/server/#vela_max_dashboard_repos) +* [`VELA_QUEUE_RESTART_LIMIT`](/reference/installation/server/#vela_queue_restart_limit) ## Configuration diff --git a/docs/reference/installation/server/token_manager.md b/docs/reference/installation/server/token_manager.md index bef81d4..b6475c1 100644 --- a/docs/reference/installation/server/token_manager.md +++ b/docs/reference/installation/server/token_manager.md @@ -15,14 +15,14 @@ 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`\`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`\`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`\`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`\`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`\`WORKER_REGISTER_TOKEN_DURATION` | +| 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`,`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`,`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`,`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`,`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`,`WORKER_REGISTER_TOKEN_DURATION` | diff --git a/docs/reference/installation/server/tracing.md b/docs/reference/installation/server/tracing.md index de9eccb..aa1f406 100644 --- a/docs/reference/installation/server/tracing.md +++ b/docs/reference/installation/server/tracing.md @@ -12,19 +12,19 @@ This component is responsible for instrumenting [OpenTelemetry traces](https://o The following options are used to configure the component: -| Name | Description | Required | Default | Environment Variables | -| --------------------------- | -------------------------------------------------------- | -------- | ------- | --------------------------------------------------------------------------- | -| `tracing.enable` | This variable enables [OpenTelemetry tracing](https://opentelemetry.io/docs/concepts/signals/traces/) for the Vela server. You must provide `VELA_OTEL_EXPORTER_OTLP_ENDPOINT` **when tracing is enabled**. | `false` | `false` | `VELA_OTEL_TRACING_ENABLE` | -| `tracing.service.name` | This variable sets the [service name](https://opentelemetry.io/docs/languages/sdk-configuration/general/) applied to [traces](https://opentelemetry.io/docs/concepts/signals/traces/). | `false` | `vela-server` | `VELA_OTEL_TRACING_SERVICE_NAME` | -| `tracing.exporter.endpoint` | This variable sets the [OTel exporter](https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/) endpoint (ex. scheme://host:port). | `false` | `N/A` | `VELA_OTEL_EXPORTER_OTLP_ENDPOINT` | -| `tracing.exporter.cert_path` | This variable sets the path to certs used for communicating with the [OTel exporter](https://opentelemetry.io/docs/specs/OTel/protocol/exporter/). If nothing is provided the server will use insecure communication. | `false` | `N/A` | `VELA_OTEL_TRACING_EXPORTER_SSL_CERT_PATH` | -| `tracing.exporter.tls-min-version` | This optional variable sets a TLS minimum version used when exporting traces to the [OTel exporter](https://opentelemetry.io/docs/specs/OTel/protocol/exporter/). | `false` | `1.2` | `VELA_OTEL_TRACING_TLS_MIN_VERSION` | -| `tracing.sampler.persecond` | This variable sets OTel [tracing head-sampler](https://opentelemetry.io/docs/concepts/sampling/) rate-limiting to N per second. | `false` | `100` | `VELA_OTEL_TRACING_SAMPLER_RATELIMIT_PER_SECOND` | -| `tracing.sampler.tasks` | This variable sets an (optional) filepath to the OTel tracing head-sampler configurations json to alter how certain tasks (API endpoints, queries, etc) are sampled. | `false` | `N/A` | `VELA_OTEL_TRACING_SAMPLER_TASKS_CONFIG_FILEPATH` | -| `tracing.resource.attributes` | This variable sets OTel resource [(span) attributes](https://opentelemetry.io/docs/languages/go/instrumentation/#span-attributes) as a list of `key=value` pairs. each one will be attached to each span as a 'process' attribute. | `false` | `N/A` | `VELA_OTEL_TRACING_RESOURCE_ATTRIBUTES` | -| `tracing.resource.env_attributes` | This variable sets OTel resource [(span) attributes](https://opentelemetry.io/docs/languages/go/instrumentation/#span-attributes) as a list of `key=env_variable_key` pairs. each one will be attached to each [span](https://opentelemetry.io/docs/languages/go/instrumentation/#span-attributes) as a 'process' attribute where the value is retrieved from the environment using the pair value. | `false` | `N/A` | `VELA_OTEL_TRACING_RESOURCE_ENV_ATTRIBUTES` | -| `tracing.span.attributes` | This variable sets trace [span attributes](https://opentelemetry.io/docs/languages/go/instrumentation/#span-attributes) as a list of `key=value` pairs. Each pair will be attached to each [span](https://opentelemetry.io/docs/languages/go/instrumentation/#span-attributes) as a 'tag' attribute. | `false` | `N/A` | `VELA_OTEL_TRACING_SPAN_ATTRIBUTES` | -| `tracing.tracestate.attributes` | This variable sets OTel tracestate [(span) attributes](https://www.w3.org/TR/trace-context) as a list of `key=value` pairs. Each pair will be inserted into the tracestate for each sampled span. | `false` | `N/A` | `VELA_OTEL_TRACING_TRACESTATE_ATTRIBUTES` | +| Name | Description | Required | Default | Environment Variables | +| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------- | ------------------------------------------------- | +| `tracing.enable` | This variable enables [OpenTelemetry tracing](https://opentelemetry.io/docs/concepts/signals/traces/) for the Vela server. You must provide `VELA_OTEL_EXPORTER_OTLP_ENDPOINT` **when tracing is enabled**. | `false` | `false` | `VELA_OTEL_TRACING_ENABLE` | +| `tracing.service.name` | This variable sets the [service name](https://opentelemetry.io/docs/languages/sdk-configuration/general/) applied to [traces](https://opentelemetry.io/docs/concepts/signals/traces/). | `false` | `vela-server` | `VELA_OTEL_TRACING_SERVICE_NAME` | +| `tracing.exporter.endpoint` | This variable sets the [OTel exporter](https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/) endpoint (ex. scheme://host:port). | `false` | `N/A` | `VELA_OTEL_EXPORTER_OTLP_ENDPOINT` | +| `tracing.exporter.cert_path` | This variable sets the path to certs used for communicating with the [OTel exporter](https://opentelemetry.io/docs/specs/OTel/protocol/exporter/). If nothing is provided the server will use insecure communication. | `false` | `N/A` | `VELA_OTEL_TRACING_EXPORTER_SSL_CERT_PATH` | +| `tracing.exporter.tls-min-version` | This optional variable sets a TLS minimum version used when exporting traces to the [OTel exporter](https://opentelemetry.io/docs/specs/OTel/protocol/exporter/). | `false` | `1.2` | `VELA_OTEL_TRACING_TLS_MIN_VERSION` | +| `tracing.sampler.persecond` | This variable sets OTel [tracing head-sampler](https://opentelemetry.io/docs/concepts/sampling/) rate-limiting to N per second. | `false` | `100` | `VELA_OTEL_TRACING_SAMPLER_RATELIMIT_PER_SECOND` | +| `tracing.sampler.tasks` | This variable sets an (optional) filepath to the OTel tracing head-sampler configurations json to alter how certain tasks (API endpoints, queries, etc) are sampled. | `false` | `N/A` | `VELA_OTEL_TRACING_SAMPLER_TASKS_CONFIG_FILEPATH` | +| `tracing.resource.attributes` | This variable sets OTel resource [(span) attributes](https://opentelemetry.io/docs/languages/go/instrumentation/#span-attributes) as a list of `key=value` pairs. each one will be attached to each span as a 'process' attribute. | `false` | `N/A` | `VELA_OTEL_TRACING_RESOURCE_ATTRIBUTES` | +| `tracing.resource.env_attributes` | This variable sets OTel resource [(span) attributes](https://opentelemetry.io/docs/languages/go/instrumentation/#span-attributes) as a list of `key=env_variable_key` pairs. each one will be attached to each [span](https://opentelemetry.io/docs/languages/go/instrumentation/#span-attributes) as a 'process' attribute where the value is retrieved from the environment using the pair value. | `false` | `N/A` | `VELA_OTEL_TRACING_RESOURCE_ENV_ATTRIBUTES` | +| `tracing.span.attributes` | This variable sets trace [span attributes](https://opentelemetry.io/docs/languages/go/instrumentation/#span-attributes) as a list of `key=value` pairs. Each pair will be attached to each [span](https://opentelemetry.io/docs/languages/go/instrumentation/#span-attributes) as a 'tag' attribute. | `false` | `N/A` | `VELA_OTEL_TRACING_SPAN_ATTRIBUTES` | +| `tracing.tracestate.attributes` | This variable sets OTel tracestate [(span) attributes](https://www.w3.org/TR/trace-context) as a list of `key=value` pairs. Each pair will be inserted into the tracestate for each sampled span. | `false` | `N/A` | `VELA_OTEL_TRACING_TRACESTATE_ATTRIBUTES` | :::note For more information on how the runtime properties are consumed, please see the [server reference](/docs/reference/installation/server/server.md). @@ -87,8 +87,8 @@ A `task` is basically the "span name" based on the work being performed. A `task If a `task` is **not** represented in the configuration file then the task will be treated normally, **with tracing enabled** using the "shared" samplers. -| Field | Type | Description | -| ----- | ----------- | ----------- | +| Field | Type | Description | +| -------- | ---- | ------------------------------------------------------------------ | | `active` | bool | Set to `false` to completely disable traces for a particular task. | Examples of trace tasks include API endpoints, gorm queries, etc. The list of tasks will change as functionality is added to the server.