From 5b27291020bf8314f536ede56509d87d8505fb3b Mon Sep 17 00:00:00 2001 From: TheBurchLog <5104941+TheBurchLog@users.noreply.github.com> Date: Thu, 15 Aug 2024 12:29:07 -0400 Subject: [PATCH] Updated Config yaml page via script --- docs/app/config_yaml.adoc | 654 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 624 insertions(+), 30 deletions(-) diff --git a/docs/app/config_yaml.adoc b/docs/app/config_yaml.adoc index c9b9817..11bd00d 100644 --- a/docs/app/config_yaml.adoc +++ b/docs/app/config_yaml.adoc @@ -34,10 +34,20 @@ This section outlines the various configuration items Beer Garden supports. | False | Enable authentication via trusted headers -| <> +| <> | str -| bg-user-groups -| The http header containing the comma separated list of the user's groups. +| bg-user-alias-mapping +| The http header containing the JSON list of the user's alias user accounts mapping + +| <> +| str +| bg-user-local-roles +| The http header containing the str list of the user's local role names + +| <> +| str +| bg-user-upstream-roles +| The http header containing the JSON list of the user's roles | <> | str @@ -59,21 +69,61 @@ This section outlines the various configuration items Beer Garden supports. | False | Use role-based authentication / authorization -| <> -| str -| None -| Path to the file containg a mapping of groups to beer garden role assignments - | <> | str | None | Path to the yaml file that defines roles used for authorization +| <> +| int +| 15 +| The Garden Admin Permission access token expiration time + +| <> +| int +| 15 +| The Operator Permission access token expiration time + +| <> +| int +| 15 +| The Plugin Admin Permission access token expiration time + +| <> +| int +| 15 +| The Read Only Permission access token expiration time + +| <> +| int +| 720 +| The Garden Admin Permission refresh token expiration time + +| <> +| int +| 720 +| The Operator Permission refresh token expiration time + +| <> +| int +| 720 +| The Plugin Admin Permission refresh token expiration time + +| <> +| int +| 720 +| The Read Only Permission refresh token expiration time + | <> | str | | Secret to use when signing authentication tokens +| <> +| str +| None +| Path to the yaml file that defines users used for authorization + | <> | str | ./children @@ -264,6 +314,11 @@ This section outlines the various configuration items Beer Garden supports. | default | The routing name for upstream Beer Gardens to use +| <> +| int +| 50 +| Amount of historical status heartbeats tracked for Garden and Connections + | <> | str | None @@ -279,6 +334,16 @@ This section outlines the various configuration items Beer Garden supports. | INFO | Log level to use if config_file is not specified +| <> +| bool +| False +| Enable elastic APM server + +| <> +| str +| None +| URL to elastic apm server. + | <> | bool | False @@ -614,6 +679,11 @@ This section outlines the various configuration items Beer Garden supports. | 10 | Amount of time between status messages +| <> +| int +| 50 +| Amount of historical status heartbeats tracked + | <> | int | 30 @@ -654,6 +724,11 @@ This section outlines the various configuration items Beer Garden supports. | 10 | Number of workers (processes) to run concurrently. +| <> +| bool +| False +| Auto refresh user interface + | <> | bool | True @@ -783,9 +858,9 @@ You can set auth.authentication_handlers.trusted_header.enabled from the environ You can set `auth.authentication_handlers.trusted_header.enabled` from the command-line by specifying `--auth-authentication_handlers-trusted_header-enabled` at Beer Garden's entrypoint. -=== auth.authentication_handlers.trusted_header.user_groups_header +=== auth.authentication_handlers.trusted_header.user_alias_mapping_header -The http header containing the comma separated list of the user's groups. +The http header containing the JSON list of the user's alias user accounts mapping |=== | Attribute | Value @@ -794,16 +869,16 @@ The http header containing the comma separated list of the user's groups. | `str` | *default* -| `bg-user-groups` +| `bg-user-alias-mapping` | *env_name* -| `BG_AUTH_AUTHENTICATION_HANDLERS_TRUSTED_HEADER_USER_GROUPS_HEADER` +| `BG_AUTH_AUTHENTICATION_HANDLERS_TRUSTED_HEADER_USER_ALIAS_MAPPING_HEADER` | *required* | `True` | *cli_name* -| `--auth-authentication_handlers-trusted_header-user-groups-header` +| `--auth-authentication_handlers-trusted_header-user-alias-mapping-header` | *fallback* | `None` @@ -812,11 +887,81 @@ The http header containing the comma separated list of the user's groups. | `None` |=== -You can set auth.authentication_handlers.trusted_header.user_groups_header from the environment by setting the environment variable `BG_AUTH_AUTHENTICATION_HANDLERS_TRUSTED_HEADER_USER_GROUPS_HEADER` +You can set auth.authentication_handlers.trusted_header.user_alias_mapping_header from the environment by setting the environment variable `BG_AUTH_AUTHENTICATION_HANDLERS_TRUSTED_HEADER_USER_ALIAS_MAPPING_HEADER` + +You can set `auth.authentication_handlers.trusted_header.user_alias_mapping_header` from the command-line by specifying `--auth-authentication_handlers-trusted_header-user-alias-mapping-header` at Beer Garden's entrypoint. + +If `auth.authentication_handlers.trusted_header.user_alias_mapping_header` is not set in any of the sources listed, it will fallback to the default value `bg-user-alias-mapping` -You can set `auth.authentication_handlers.trusted_header.user_groups_header` from the command-line by specifying `--auth-authentication_handlers-trusted_header-user-groups-header` at Beer Garden's entrypoint. +=== auth.authentication_handlers.trusted_header.user_local_roles_header -If `auth.authentication_handlers.trusted_header.user_groups_header` is not set in any of the sources listed, it will fallback to the default value `bg-user-groups` +The http header containing the str list of the user's local role names + +|=== +| Attribute | Value + +| *item_type* +| `str` + +| *default* +| `bg-user-local-roles` + +| *env_name* +| `BG_AUTH_AUTHENTICATION_HANDLERS_TRUSTED_HEADER_USER_LOCAL_ROLES_HEADER` + +| *required* +| `True` + +| *cli_name* +| `--auth-authentication_handlers-trusted_header-user-local-roles-header` + +| *fallback* +| `None` + +| *choices* +| `None` +|=== + +You can set auth.authentication_handlers.trusted_header.user_local_roles_header from the environment by setting the environment variable `BG_AUTH_AUTHENTICATION_HANDLERS_TRUSTED_HEADER_USER_LOCAL_ROLES_HEADER` + +You can set `auth.authentication_handlers.trusted_header.user_local_roles_header` from the command-line by specifying `--auth-authentication_handlers-trusted_header-user-local-roles-header` at Beer Garden's entrypoint. + +If `auth.authentication_handlers.trusted_header.user_local_roles_header` is not set in any of the sources listed, it will fallback to the default value `bg-user-local-roles` + +=== auth.authentication_handlers.trusted_header.user_upstream_roles_header + +The http header containing the JSON list of the user's roles + +|=== +| Attribute | Value + +| *item_type* +| `str` + +| *default* +| `bg-user-upstream-roles` + +| *env_name* +| `BG_AUTH_AUTHENTICATION_HANDLERS_TRUSTED_HEADER_USER_UPSTREAM_ROLES_HEADER` + +| *required* +| `True` + +| *cli_name* +| `--auth-authentication_handlers-trusted_header-user-upstream-roles-header` + +| *fallback* +| `None` + +| *choices* +| `None` +|=== + +You can set auth.authentication_handlers.trusted_header.user_upstream_roles_header from the environment by setting the environment variable `BG_AUTH_AUTHENTICATION_HANDLERS_TRUSTED_HEADER_USER_UPSTREAM_ROLES_HEADER` + +You can set `auth.authentication_handlers.trusted_header.user_upstream_roles_header` from the command-line by specifying `--auth-authentication_handlers-trusted_header-user-upstream-roles-header` at Beer Garden's entrypoint. + +If `auth.authentication_handlers.trusted_header.user_upstream_roles_header` is not set in any of the sources listed, it will fallback to the default value `bg-user-upstream-roles` === auth.authentication_handlers.trusted_header.username_header @@ -956,9 +1101,9 @@ You can set auth.enabled from the environment by setting the environment variabl You can set `auth.enabled` from the command-line by specifying `--auth-enabled` at Beer Garden's entrypoint. -=== auth.group_definition_file +=== auth.role_definition_file -Path to the file containg a mapping of groups to beer garden role assignments +Path to the yaml file that defines roles used for authorization |=== | Attribute | Value @@ -970,13 +1115,13 @@ Path to the file containg a mapping of groups to beer garden role assignments | `None` | *env_name* -| `BG_AUTH_GROUP_DEFINITION_FILE` +| `BG_AUTH_ROLE_DEFINITION_FILE` | *required* | `False` | *cli_name* -| `--auth-group-definition-file` +| `--auth-role-definition-file` | *fallback* | `None` @@ -985,31 +1130,101 @@ Path to the file containg a mapping of groups to beer garden role assignments | `None` |=== -You can set auth.group_definition_file from the environment by setting the environment variable `BG_AUTH_GROUP_DEFINITION_FILE` +You can set auth.role_definition_file from the environment by setting the environment variable `BG_AUTH_ROLE_DEFINITION_FILE` -You can set `auth.group_definition_file` from the command-line by specifying `--auth-group-definition-file` at Beer Garden's entrypoint. +You can set `auth.role_definition_file` from the command-line by specifying `--auth-role-definition-file` at Beer Garden's entrypoint. -=== auth.role_definition_file +=== auth.token_access_ttl.garden_admin -Path to the yaml file that defines roles used for authorization +The Garden Admin Permission access token expiration time |=== | Attribute | Value | *item_type* -| `str` +| `int` + +| *default* +| `15` + +| *env_name* +| `BG_AUTH_TOKEN_ACCESS_TTL_GARDEN_ADMIN` + +| *required* +| `True` + +| *cli_name* +| `--auth-token_access_ttl-garden-admin` + +| *fallback* +| `None` + +| *choices* +| `None` +|=== + +You can set auth.token_access_ttl.garden_admin from the environment by setting the environment variable `BG_AUTH_TOKEN_ACCESS_TTL_GARDEN_ADMIN` + +You can set `auth.token_access_ttl.garden_admin` from the command-line by specifying `--auth-token_access_ttl-garden-admin` at Beer Garden's entrypoint. + +If `auth.token_access_ttl.garden_admin` is not set in any of the sources listed, it will fallback to the default value `15` + +=== auth.token_access_ttl.operator + +The Operator Permission access token expiration time + +|=== +| Attribute | Value + +| *item_type* +| `int` | *default* +| `15` + +| *env_name* +| `BG_AUTH_TOKEN_ACCESS_TTL_OPERATOR` + +| *required* +| `True` + +| *cli_name* +| `--auth-token_access_ttl-operator` + +| *fallback* | `None` +| *choices* +| `None` +|=== + +You can set auth.token_access_ttl.operator from the environment by setting the environment variable `BG_AUTH_TOKEN_ACCESS_TTL_OPERATOR` + +You can set `auth.token_access_ttl.operator` from the command-line by specifying `--auth-token_access_ttl-operator` at Beer Garden's entrypoint. + +If `auth.token_access_ttl.operator` is not set in any of the sources listed, it will fallback to the default value `15` + +=== auth.token_access_ttl.plugin_admin + +The Plugin Admin Permission access token expiration time + +|=== +| Attribute | Value + +| *item_type* +| `int` + +| *default* +| `15` + | *env_name* -| `BG_AUTH_ROLE_DEFINITION_FILE` +| `BG_AUTH_TOKEN_ACCESS_TTL_PLUGIN_ADMIN` | *required* -| `False` +| `True` | *cli_name* -| `--auth-role-definition-file` +| `--auth-token_access_ttl-plugin-admin` | *fallback* | `None` @@ -1018,9 +1233,186 @@ Path to the yaml file that defines roles used for authorization | `None` |=== -You can set auth.role_definition_file from the environment by setting the environment variable `BG_AUTH_ROLE_DEFINITION_FILE` +You can set auth.token_access_ttl.plugin_admin from the environment by setting the environment variable `BG_AUTH_TOKEN_ACCESS_TTL_PLUGIN_ADMIN` -You can set `auth.role_definition_file` from the command-line by specifying `--auth-role-definition-file` at Beer Garden's entrypoint. +You can set `auth.token_access_ttl.plugin_admin` from the command-line by specifying `--auth-token_access_ttl-plugin-admin` at Beer Garden's entrypoint. + +If `auth.token_access_ttl.plugin_admin` is not set in any of the sources listed, it will fallback to the default value `15` + +=== auth.token_access_ttl.read_only + +The Read Only Permission access token expiration time + +|=== +| Attribute | Value + +| *item_type* +| `int` + +| *default* +| `15` + +| *env_name* +| `BG_AUTH_TOKEN_ACCESS_TTL_READ_ONLY` + +| *required* +| `True` + +| *cli_name* +| `--auth-token_access_ttl-read-only` + +| *fallback* +| `None` + +| *choices* +| `None` +|=== + +You can set auth.token_access_ttl.read_only from the environment by setting the environment variable `BG_AUTH_TOKEN_ACCESS_TTL_READ_ONLY` + +You can set `auth.token_access_ttl.read_only` from the command-line by specifying `--auth-token_access_ttl-read-only` at Beer Garden's entrypoint. + +If `auth.token_access_ttl.read_only` is not set in any of the sources listed, it will fallback to the default value `15` + +=== auth.token_refresh_ttl.garden_admin + +The Garden Admin Permission refresh token expiration time + +|=== +| Attribute | Value + +| *item_type* +| `int` + +| *default* +| `720` + +| *env_name* +| `BG_AUTH_TOKEN_REFRESH_TTL_GARDEN_ADMIN` + +| *required* +| `True` + +| *cli_name* +| `--auth-token_refresh_ttl-garden-admin` + +| *fallback* +| `None` + +| *choices* +| `None` +|=== + +You can set auth.token_refresh_ttl.garden_admin from the environment by setting the environment variable `BG_AUTH_TOKEN_REFRESH_TTL_GARDEN_ADMIN` + +You can set `auth.token_refresh_ttl.garden_admin` from the command-line by specifying `--auth-token_refresh_ttl-garden-admin` at Beer Garden's entrypoint. + +If `auth.token_refresh_ttl.garden_admin` is not set in any of the sources listed, it will fallback to the default value `720` + +=== auth.token_refresh_ttl.operator + +The Operator Permission refresh token expiration time + +|=== +| Attribute | Value + +| *item_type* +| `int` + +| *default* +| `720` + +| *env_name* +| `BG_AUTH_TOKEN_REFRESH_TTL_OPERATOR` + +| *required* +| `True` + +| *cli_name* +| `--auth-token_refresh_ttl-operator` + +| *fallback* +| `None` + +| *choices* +| `None` +|=== + +You can set auth.token_refresh_ttl.operator from the environment by setting the environment variable `BG_AUTH_TOKEN_REFRESH_TTL_OPERATOR` + +You can set `auth.token_refresh_ttl.operator` from the command-line by specifying `--auth-token_refresh_ttl-operator` at Beer Garden's entrypoint. + +If `auth.token_refresh_ttl.operator` is not set in any of the sources listed, it will fallback to the default value `720` + +=== auth.token_refresh_ttl.plugin_admin + +The Plugin Admin Permission refresh token expiration time + +|=== +| Attribute | Value + +| *item_type* +| `int` + +| *default* +| `720` + +| *env_name* +| `BG_AUTH_TOKEN_REFRESH_TTL_PLUGIN_ADMIN` + +| *required* +| `True` + +| *cli_name* +| `--auth-token_refresh_ttl-plugin-admin` + +| *fallback* +| `None` + +| *choices* +| `None` +|=== + +You can set auth.token_refresh_ttl.plugin_admin from the environment by setting the environment variable `BG_AUTH_TOKEN_REFRESH_TTL_PLUGIN_ADMIN` + +You can set `auth.token_refresh_ttl.plugin_admin` from the command-line by specifying `--auth-token_refresh_ttl-plugin-admin` at Beer Garden's entrypoint. + +If `auth.token_refresh_ttl.plugin_admin` is not set in any of the sources listed, it will fallback to the default value `720` + +=== auth.token_refresh_ttl.read_only + +The Read Only Permission refresh token expiration time + +|=== +| Attribute | Value + +| *item_type* +| `int` + +| *default* +| `720` + +| *env_name* +| `BG_AUTH_TOKEN_REFRESH_TTL_READ_ONLY` + +| *required* +| `True` + +| *cli_name* +| `--auth-token_refresh_ttl-read-only` + +| *fallback* +| `None` + +| *choices* +| `None` +|=== + +You can set auth.token_refresh_ttl.read_only from the environment by setting the environment variable `BG_AUTH_TOKEN_REFRESH_TTL_READ_ONLY` + +You can set `auth.token_refresh_ttl.read_only` from the command-line by specifying `--auth-token_refresh_ttl-read-only` at Beer Garden's entrypoint. + +If `auth.token_refresh_ttl.read_only` is not set in any of the sources listed, it will fallback to the default value `720` === auth.token_secret @@ -1055,6 +1447,39 @@ You can set auth.token_secret from the environment by setting the environment va You can set `auth.token_secret` from the command-line by specifying `--auth-token-secret` at Beer Garden's entrypoint. +=== auth.user_definition_file + +Path to the yaml file that defines users used for authorization + +|=== +| Attribute | Value + +| *item_type* +| `str` + +| *default* +| `None` + +| *env_name* +| `BG_AUTH_USER_DEFINITION_FILE` + +| *required* +| `False` + +| *cli_name* +| `--auth-user-definition-file` + +| *fallback* +| `None` + +| *choices* +| `None` +|=== + +You can set auth.user_definition_file from the environment by setting the environment variable `BG_AUTH_USER_DEFINITION_FILE` + +You can set `auth.user_definition_file` from the command-line by specifying `--auth-user-definition-file` at Beer Garden's entrypoint. + === children.directory Directory where child garden configs are located @@ -2347,6 +2772,41 @@ You can set `garden.name` from the command-line by specifying `--garden-name` at If `garden.name` is not set in any of the sources listed, it will fallback to the default value `default` +=== garden.status_history + +Amount of historical status heartbeats tracked for Garden and Connections + +|=== +| Attribute | Value + +| *item_type* +| `int` + +| *default* +| `50` + +| *env_name* +| `BG_GARDEN_STATUS_HISTORY` + +| *required* +| `True` + +| *cli_name* +| `--garden-status-history` + +| *fallback* +| `None` + +| *choices* +| `None` +|=== + +You can set garden.status_history from the environment by setting the environment variable `BG_GARDEN_STATUS_HISTORY` + +You can set `garden.status_history` from the command-line by specifying `--garden-status-history` at Beer Garden's entrypoint. + +If `garden.status_history` is not set in any of the sources listed, it will fallback to the default value `50` + === log.config_file Path to a logging config file. @@ -2448,6 +2908,72 @@ You can set `log.fallback_level` from the command-line by specifying `--log-fall If `log.fallback_level` is not set in any of the sources listed, it will fallback to the default value `INFO` +=== metrics.elastic.enabled + +Enable elastic APM server + +|=== +| Attribute | Value + +| *item_type* +| `bool` + +| *default* +| `False` + +| *env_name* +| `BG_METRICS_ELASTIC_ENABLED` + +| *required* +| `True` + +| *cli_name* +| `--metrics-elastic-enabled` + +| *fallback* +| `None` + +| *choices* +| `None` +|=== + +You can set metrics.elastic.enabled from the environment by setting the environment variable `BG_METRICS_ELASTIC_ENABLED` + +You can set `metrics.elastic.enabled` from the command-line by specifying `--metrics-elastic-enabled` at Beer Garden's entrypoint. + +=== metrics.elastic.url + +URL to elastic apm server. + +|=== +| Attribute | Value + +| *item_type* +| `str` + +| *default* +| `None` + +| *env_name* +| `BG_METRICS_ELASTIC_URL` + +| *required* +| `False` + +| *cli_name* +| `--metrics-elastic-url` + +| *fallback* +| `None` + +| *choices* +| `None` +|=== + +You can set metrics.elastic.url from the environment by setting the environment variable `BG_METRICS_ELASTIC_URL` + +You can set `metrics.elastic.url` from the command-line by specifying `--metrics-elastic-url` at Beer Garden's entrypoint. + === metrics.prometheus.enabled Enable prometheus server @@ -4725,6 +5251,41 @@ You can set `plugin.status_heartbeat` from the command-line by specifying `--plu If `plugin.status_heartbeat` is not set in any of the sources listed, it will fallback to the default value `10` +=== plugin.status_history + +Amount of historical status heartbeats tracked + +|=== +| Attribute | Value + +| *item_type* +| `int` + +| *default* +| `50` + +| *env_name* +| `BG_PLUGIN_STATUS_HISTORY` + +| *required* +| `True` + +| *cli_name* +| `--plugin-status-history` + +| *fallback* +| `None` + +| *choices* +| `None` +|=== + +You can set plugin.status_history from the environment by setting the environment variable `BG_PLUGIN_STATUS_HISTORY` + +You can set `plugin.status_history` from the command-line by specifying `--plugin-status-history` at Beer Garden's entrypoint. + +If `plugin.status_history` is not set in any of the sources listed, it will fallback to the default value `50` + === plugin.status_timeout Amount of time to wait before marking a plugin asunresponsive @@ -5001,6 +5562,39 @@ You can set `scheduler.max_workers` from the command-line by specifying `--sched If `scheduler.max_workers` is not set in any of the sources listed, it will fallback to the default value `10` +=== ui.auto_refresh + +Auto refresh user interface + +|=== +| Attribute | Value + +| *item_type* +| `bool` + +| *default* +| `False` + +| *env_name* +| `BG_UI_AUTO_REFRESH` + +| *required* +| `True` + +| *cli_name* +| `--ui-auto-refresh` + +| *fallback* +| `None` + +| *choices* +| `None` +|=== + +You can set ui.auto_refresh from the environment by setting the environment variable `BG_UI_AUTO_REFRESH` + +You can set `ui.auto_refresh` from the command-line by specifying `--ui-auto-refresh` at Beer Garden's entrypoint. + === ui.cors_enabled Determine if CORS should be enabled