From 16e514507dc685f567f4fc9d201f59cfcfdb6cbe Mon Sep 17 00:00:00 2001 From: Adam Urban Date: Mon, 16 Dec 2024 17:20:24 +0100 Subject: [PATCH] feat(self-managed/console): describe tls config (#4317) * feat(self-managed/console): describe tls config * style(formatting): grammatical adjustments * update application config links to point to correct version * Restructure content --------- Co-authored-by: Christina Ausley Co-authored-by: Cole Garbo --- .../{ => configuration}/configuration.md | 38 +++++++------ .../console-deployment/configuration/ssl.md | 53 +++++++++++++++++++ .../console-deployment/telemetry.md | 2 +- .../operational-guides/application-configs.md | 16 +++--- sidebars.js | 7 ++- .../operational-guides/application-configs.md | 16 +++--- 6 files changed, 99 insertions(+), 33 deletions(-) rename docs/self-managed/console-deployment/{ => configuration}/configuration.md (65%) create mode 100644 docs/self-managed/console-deployment/configuration/ssl.md diff --git a/docs/self-managed/console-deployment/configuration.md b/docs/self-managed/console-deployment/configuration/configuration.md similarity index 65% rename from docs/self-managed/console-deployment/configuration.md rename to docs/self-managed/console-deployment/configuration/configuration.md index 25d4b40162e..1c09cea48e1 100644 --- a/docs/self-managed/console-deployment/configuration.md +++ b/docs/self-managed/console-deployment/configuration/configuration.md @@ -1,7 +1,7 @@ --- id: configuration -title: "Configuration" -sidebar_label: "Configuration" +title: "Console configuration" +sidebar_label: "Overview" description: "Read details on the configuration variables of Console Self-Managed." --- @@ -13,19 +13,27 @@ Underscores in environment variables correspond to configuration file key levels ## Environment variables -| Environment variable | Description | Example value | -| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | -| `KEYCLOAK_BASE_URL` | Base URL for Keycloak | https://example.com/auth | -| `KEYCLOAK_INTERNAL_BASE_URL` | Internal Base URL for Keycloak | http://camunda-platform-keycloak:80/auth | -| `KEYCLOAK_REALM` | Realm for Keycloak | camunda-platform | -| `CAMUNDA_IDENTITY_AUDIENCE` | Audience for Console client | console | -| `CAMUNDA_IDENTITY_CLIENT_ID` | Client ID for Console client | console | -| `CAMUNDA_CONSOLE_CONTEXT_PATH` | Context path for Console | console | -| `CAMUNDA_CONSOLE_CUSTOMERID` | Unique identifier of the customer | `customer-id` | -| `CAMUNDA_CONSOLE_INSTALLATIONID` | Unique installation ID of the current customer installation | `installation-id` | -| `CAMUNDA_CONSOLE_TELEMETRY` | Telemetry config for Console Self-Managed: `disabled`, `online`, or `download` | `online` | -| `CAMUNDA_CONSOLE_DISABLE_AUTH` | Disables authentication for Console. With this option, set users don't have to log in to use Console and API requests can be executed without an Authorization header.
By disabling authentication all `CAMUNDA_IDENTITY`, variables won't be used. | `true` | -| `CAMUNDA_LICENSE_KEY` | Your Camunda 8 license key, if your installation requires a license. For Helm installations, license keys can be configured globally in your `values.yaml` file. See the [Helm installation documentation](/self-managed/setup/install.md#configure-license-key) for more details. | N/A | +| Environment variable | Description | Example value | +| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | +| `KEYCLOAK_BASE_URL` | Base URL for Keycloak | https://example.com/auth | +| `KEYCLOAK_INTERNAL_BASE_URL` | Internal base URL for Keycloak | http://camunda-platform-keycloak:80/auth | +| `KEYCLOAK_REALM` | Realm for Keycloak | camunda-platform | +| `CAMUNDA_IDENTITY_AUDIENCE` | Audience for Console client | console | +| `CAMUNDA_IDENTITY_CLIENT_ID` | Client ID for Console client | console | +| `CAMUNDA_CONSOLE_CONTEXT_PATH` | Context path for Console | console | +| `CAMUNDA_CONSOLE_CUSTOMERID` | Unique identifier of the customer | `customer-id` | +| `CAMUNDA_CONSOLE_INSTALLATIONID` | Unique installation ID of the current customer installation | `installation-id` | +| `CAMUNDA_CONSOLE_TELEMETRY` | Telemetry config for Console Self-Managed: `disabled`, `online`, or `download` | `online` | +| `CAMUNDA_CONSOLE_DISABLE_AUTH` | Disables authentication for Console. With this option, set users don't have to log in to use Console and API requests can be executed without an authorization header.
By disabling authentication, all `CAMUNDA_IDENTITY` variables won't be used. | `true` | +| `CAMUNDA_LICENSE_KEY` | Your Camunda 8 license key, if your installation requires a license. For Helm installations, license keys can be configured globally in your `values.yaml` file. See the [Helm installation documentation](/self-managed/setup/install.md#configure-license-key) for more details. | N/A | +| `SERVER_SSL_ENABLED` | [optional]
Whether to enable SSL support.
Default: `false` | `true` | +| `SERVER_SSL_CERTIFICATE` | [optional]
Path to a PEM-encoded SSL certificate file. | `file:/full/path/to/certificate.pem` | +| `SERVER_SSL_CERTIFICATE_PRIVATE_KEY` | [optional]
Path to a PEM-encoded private key file for the SSL certificate. | `file:/full/path/to/key.pem` | +| `SERVER_SSL_PASSPHRASE` | [optional]
Passphrase for the key. | `passphrase` | +| `MANAGEMENT_SERVER_SSL_ENABLED` | [optional]
Whether to enable SSL support for the management server routes.
Default: `false` | `true` | +| `MANAGEMENT_SERVER_SSL_CERTIFICATE` | [optional]
Path to a PEM-encoded SSL certificate file. | `file:/full/path/to/certificate.pem` | +| `MANAGEMENT_SERVER_SSL_CERTIFICATE_PRIVATE_KEY` | [optional]
Path to a PEM-encoded private key file for the SSL certificate. | `file:/full/path/to/key.pem` | +| `MANAGEMENT_SERVER_SSL_PASSPHRASE` | [optional]
Passphrase for the key. | `passphrase` | Console environment variables could be set in Helm via the `console.env` key. For more details, check [Console Helm values](https://artifacthub.io/packages/helm/camunda/camunda-platform#console-parameters). diff --git a/docs/self-managed/console-deployment/configuration/ssl.md b/docs/self-managed/console-deployment/configuration/ssl.md new file mode 100644 index 00000000000..e74aa635e3f --- /dev/null +++ b/docs/self-managed/console-deployment/configuration/ssl.md @@ -0,0 +1,53 @@ +--- +id: ssl +title: "Console SSL configuration" +sidebar_label: "SSL" +description: "Read details on additional SSL configuration for Console." +--- + +By default, communication between Console, Identity, and other components is not encrypted, as it usually occurs backend-to-backend within the same [Docker](/self-managed/setup/deploy/other/docker.md) network or [Kubernetes](/self-managed/setup/install.md) cluster. + +TLS-encrypted communication can be enabled by following the steps below (for example, if backend-to-backend communication is not possible in a custom Camunda 8 installation setup). + +## Configure Console for secure connections + +Console can be configured using [environment variables](/self-managed/console-deployment/configuration/configuration.md#environment-variables) to enable secure connections to both Console and Identity. + +### Configure the Identity base URL + +Set the base URL (starting with `https://`) of your Identity instance using the following properties: + +| Environment variable | Example value | +| ---------------------------- | ------------------------------ | +| `KEYCLOAK_BASE_URL` | `https://identity.example.com` | +| `KEYCLOAK_INTERNAL_BASE_URL` | `https://identity.example.com` | + +### Configure SSL certificate + +Enable and configure SSL by setting the following properties: + +| Environment variable | Description | Example value | +| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------ | +| `SERVER_SSL_ENABLED` | To enable SSL, set to `true`. | `true` | +| `SERVER_SSL_CERTIFICATE` | The path to a PEM-encoded SSL certificate file. Ensure the provided path is accessible from the container (for example, via a mounted volume). | `file:/full/path/to/certificate.pem` | +| `SERVER_SSL_CERTIFICATE_PRIVATE_KEY` | The path to a PEM-encoded private key file for the SSL certificate. Ensure the provided path is accessible from the container (for example, via a mounted volume). | `file:/full/path/to/key.pem` | +| `SERVER_SSL_PASSPHRASE` | _Optional_ A passphrase for the private key. | `passphrase` | + +SSL can be configured separately for the management routes using the `MANAGEMENT_` properties: + +| Environment variable | Description | Example value | +| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------ | +| `MANAGEMENT_SERVER_SSL_ENABLED` | To enable SSL, set to `true`. | `true` | +| `MANAGEMENT_SERVER_SSL_CERTIFICATE` | The path to a PEM-encoded SSL certificate file. Ensure the provided path is accessible from the container (for example, via a mounted volume). | `file:/full/path/to/certificate.pem` | +| `MANAGEMENT_SERVER_SSL_CERTIFICATE_PRIVATE_KEY` | The path to a PEM-encoded private key file for the SSL certificate. Ensure the provided path is accessible from the container (for example, via a mounted volume). | `file:/full/path/to/key.pem` | +| `MANAGEMENT_SERVER_SSL_PASSPHRASE` | _Optional_ A passphrase for the private key. | `passphrase` | + +## (Optional) Provide a custom certificate + +If you are using a custom (self-signed) TLS certificate in Console or Identity, configure Console to accept the certificate. + +Provide the path to the certificate file via the environment variable `NODE_EXTRA_CA_CERTS`: + +| Environment variable | Description | Example value | +| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | +| `NODE_EXTRA_CA_CERTS` | The path to your self-signed TLS certificate. Ensure the provided path is accessible from the container (for example, via a mounted volume). | `/path/to/certificate.crt` | diff --git a/docs/self-managed/console-deployment/telemetry.md b/docs/self-managed/console-deployment/telemetry.md index 08b19f22140..fda37c67c13 100644 --- a/docs/self-managed/console-deployment/telemetry.md +++ b/docs/self-managed/console-deployment/telemetry.md @@ -24,7 +24,7 @@ The telemetry feature categorizes the collected data into general Camunda data a ### How to enable telemetry -By default, the telemetry configuration is set to `disabled`. Telemetry can be activated by setting the appropriate configuration in the Camunda 8 Helm chart or setting the appropriate environment variables in the Console configuration. Refer to [Console configuration](./configuration.md) for more information. +By default, the telemetry configuration is set to `disabled`. Telemetry can be activated by setting the appropriate configuration in the Camunda 8 Helm chart or setting the appropriate environment variables in the Console configuration. Refer to [Console configuration](./configuration/configuration.md) for more information. ### Telemetry configuration options explained diff --git a/docs/self-managed/operational-guides/application-configs.md b/docs/self-managed/operational-guides/application-configs.md index b4b1363f075..b021fb22c0c 100644 --- a/docs/self-managed/operational-guides/application-configs.md +++ b/docs/self-managed/operational-guides/application-configs.md @@ -209,14 +209,14 @@ Then, take the contents under `application.yml` and put it under the `operate.co ## Where to search for configuration options -- [Zeebe Broker](docs/self-managed/zeebe-deployment/configuration/broker.md) -- [Zeebe Gateway](docs/self-managed/zeebe-deployment/configuration/gateway.md) -- [Operate](docs/self-managed/operate-deployment/operate-configuration.md) -- [Tasklist](docs/self-managed/tasklist-deployment/tasklist-configuration.md) -- [Web Modeler](docs/self-managed/modeler/web-modeler/configuration/configuration.md) -- [Console](docs/self-managed/console-deployment/configuration.md) -- [Connectors](docs/self-managed/connectors-deployment/connectors-configuration.md) -- [Identity](docs/self-managed/identity/deployment/configuration-variables.md) +- [Zeebe Broker](/self-managed/zeebe-deployment/configuration/broker.md) +- [Zeebe Gateway](/self-managed/zeebe-deployment/configuration/gateway.md) +- [Operate](/self-managed/operate-deployment/operate-configuration.md) +- [Tasklist](/self-managed/tasklist-deployment/tasklist-configuration.md) +- [Web Modeler](/self-managed/modeler/web-modeler/configuration/configuration.md) +- [Console](/self-managed/console-deployment/configuration/configuration.md) +- [Connectors](/self-managed/connectors-deployment/connectors-configuration.md) +- [Identity](/self-managed/identity/deployment/configuration-variables.md) - [Optimize]($optimize$/self-managed/optimize-deployment/configuration/system-configuration) ## Limitations diff --git a/sidebars.js b/sidebars.js index 34f89302958..a0a051088da 100644 --- a/sidebars.js +++ b/sidebars.js @@ -1098,7 +1098,12 @@ module.exports = { Console: [ "self-managed/console-deployment/overview", "self-managed/console-deployment/installation", - "self-managed/console-deployment/configuration", + { + Configuration: [ + "self-managed/console-deployment/configuration/configuration", + "self-managed/console-deployment/configuration/ssl", + ], + }, "self-managed/console-deployment/telemetry", ], Zeebe: [ diff --git a/versioned_docs/version-8.5/self-managed/operational-guides/application-configs.md b/versioned_docs/version-8.5/self-managed/operational-guides/application-configs.md index 9123d8c4813..6231578062b 100644 --- a/versioned_docs/version-8.5/self-managed/operational-guides/application-configs.md +++ b/versioned_docs/version-8.5/self-managed/operational-guides/application-configs.md @@ -208,14 +208,14 @@ Then, take the contents under `application.yml` and put it under the `operate.co ## Where to search for configuration options -- [Zeebe Broker](docs/self-managed/zeebe-deployment/configuration/broker.md) -- [Zeebe Gateway](docs/self-managed/zeebe-deployment/configuration/gateway.md) -- [Operate](docs/self-managed/operate-deployment/operate-configuration.md) -- [Tasklist](docs/self-managed/tasklist-deployment/tasklist-configuration.md) -- [Web Modeler](docs/self-managed/modeler/web-modeler/configuration/configuration.md) -- [Console](docs/self-managed/console-deployment/configuration.md) -- [Connectors](docs/self-managed/connectors-deployment/connectors-configuration.md) -- [Identity](docs/self-managed/identity/deployment/configuration-variables.md) +- [Zeebe Broker](/self-managed/zeebe-deployment/configuration/broker.md) +- [Zeebe Gateway](/self-managed/zeebe-deployment/configuration/gateway.md) +- [Operate](/self-managed/operate-deployment/operate-configuration.md) +- [Tasklist](/self-managed/tasklist-deployment/tasklist-configuration.md) +- [Web Modeler](/self-managed/modeler/web-modeler/configuration/configuration.md) +- [Console](/self-managed/console-deployment/configuration.md) +- [Connectors](/self-managed/connectors-deployment/connectors-configuration.md) +- [Identity](/self-managed/identity/deployment/configuration-variables.md) - [Optimize]($optimize$/self-managed/optimize-deployment/configuration/system-configuration) ## Limitations