From 31d281f09305ca1d517d3edd3d44352f045a6335 Mon Sep 17 00:00:00 2001 From: Alex Chapellon Date: Thu, 28 Mar 2024 13:50:41 +0100 Subject: [PATCH] OPSEXP-146: add documentation on how to configure APS databases (#259) --- charts/alfresco-process-services/Chart.yaml | 2 +- charts/alfresco-process-services/README.md | 2 +- .../docs/databases-configuration.md | 100 ++++++++++++++++++ .../docs/elasticsearch-configuration.md | 47 ++++++++ 4 files changed, 149 insertions(+), 2 deletions(-) create mode 100644 charts/alfresco-process-services/docs/databases-configuration.md create mode 100644 charts/alfresco-process-services/docs/elasticsearch-configuration.md diff --git a/charts/alfresco-process-services/Chart.yaml b/charts/alfresco-process-services/Chart.yaml index 4dfc70e8..eafa40ff 100644 --- a/charts/alfresco-process-services/Chart.yaml +++ b/charts/alfresco-process-services/Chart.yaml @@ -1,7 +1,7 @@ apiVersion: v2 description: A Helm chart for Alfresco Process Services name: alfresco-process-services -version: 1.0.0-alpha.2 +version: 1.0.0-alpha.3 appVersion: 24.1.0 dependencies: - name: alfresco-common diff --git a/charts/alfresco-process-services/README.md b/charts/alfresco-process-services/README.md index fe67d644..de53f27b 100644 --- a/charts/alfresco-process-services/README.md +++ b/charts/alfresco-process-services/README.md @@ -1,6 +1,6 @@ # alfresco-process-services -![Version: 1.0.0-alpha.2](https://img.shields.io/badge/Version-1.0.0--alpha.2-informational?style=flat-square) ![AppVersion: 24.1.0](https://img.shields.io/badge/AppVersion-24.1.0-informational?style=flat-square) +![Version: 1.0.0-alpha.3](https://img.shields.io/badge/Version-1.0.0--alpha.3-informational?style=flat-square) ![AppVersion: 24.1.0](https://img.shields.io/badge/AppVersion-24.1.0-informational?style=flat-square) A Helm chart for Alfresco Process Services diff --git a/charts/alfresco-process-services/docs/databases-configuration.md b/charts/alfresco-process-services/docs/databases-configuration.md new file mode 100644 index 00000000..456d07f4 --- /dev/null +++ b/charts/alfresco-process-services/docs/databases-configuration.md @@ -0,0 +1,100 @@ +# Alfresco Process Service database configuration + +Alfresco Process Service uses a relational database to store data. An additional +database is required in order to deploy the APS admin application. + +> It is not possible to use the same database for both applications. Though, +> both databases can be hosted on the same database server. + +## Configuring the APS database + +This charts uses generic configuration means reused in all our charts. You +should start reading the +[getting-started](../../docs/getting-started-with-alfresco-charts.md) guide. + +### Using values + +The most straightforward way to configure the APS database is to use the Helm +values file. The following example shows how to configure the APS database: + +```yaml +processEngine: + database: + url: jdbc:postgresql://postgresql:5432/activiti + username: alfresco + password: alfresco +``` + +### Using a ConfigMap & Secret + +Another and more production-ready way to configure the APS database is to use +configmaps and secrets from an umbrella chart. This chart depends on the +`alfresco-common` library chart, which provides a named template to ease +creation of the database configuration. Below is an example which assumes the +alfresco-process-services chart is set as a dependency in the umbrella chart +and values are configured as follows: + +```yaml +# apsdb could be anything else, it is just a name +apsdb: + url: jdbc:mysql://mysql:3306/activiti +alfresco-process-services: + processEngine: + database: + existingConfigMap: + name: my-database-config +``` + +Then create a ConfigMap template with the following content: + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: my-database-config +data: + {{ template "alfresco-process-services.db.cm" .Values.apsdb }} +``` + +If you chose to not use the "alfresco-process-services.db.cm" helper template, +you need to make sure you also provide the `DATABASE_DRIVER` key in the +configmap. The helper will try autodetect which class to use based on the URL +provided. + +> If you want to use a custom driver class, you can provide it in the +> `apsdb.driver` value. + +For the secret there is no helper and you need to provide one secret which +contains 2 data keys: + +* DATABASE_USERNAME +* DATABASE_PASSWORD + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: my-database-secret +type: Opaque +data: + DATABASE_USERNAME: {{ .Values.apsdb.username | b64enc | quote }} + DATABASE_PASSWORD: {{ .Values.apsdb.password | b64enc | quote }} +``` + +You may want to reuse a secret which is already created in your cluster but has +different keys. In this case you would need to configure the +alfresco-process-services chart as follows: + +```yaml +alfresco-process-services: + processEngine: + database: + existingSecret: + name: my-database-secret + keys: + username: MY_DATABASE_USERNAME + password: MY_DATABASE_PASSWORD +``` + +The exact same approach can be used to configure the APS admin application, in +which case the `adminApp` key should be used instead of `processEngine`. diff --git a/charts/alfresco-process-services/docs/elasticsearch-configuration.md b/charts/alfresco-process-services/docs/elasticsearch-configuration.md new file mode 100644 index 00000000..a39dead1 --- /dev/null +++ b/charts/alfresco-process-services/docs/elasticsearch-configuration.md @@ -0,0 +1,47 @@ +# Alfresco Process Services search index configuration + +Alfresco Process Services can use an Elasticsearch index. This document provides +information on how to configure the search index in Alfresco Process Services. + +## Elasticsearch configuration + +It is quite common to tie Alfresco Process Services to an Elasticsearch index +which lives outside of the Kubernetes cluster. For example your index might be +provided by a managed Elasticsearch service such as AWS OpenSearch. + +> APS for now only support ElasticSearch 7.x + +In order to connect to an external Elasticsearch index, you need to configure +the following properties in the `values.yaml` file: + +```yaml +processEngine: + environment: + ACTIVITI_ES_REST_CLIENT_ADDRESS: vpc-id.region.es.amazonaws.com + ACTIVITI_ES_REST_CLIENT_PORT: 443 + ACTIVITI_ES_REST_CLIENT_SCHEMA: https + ACTIVITI_ES_REST_CLIENT_AUTH_ENABLED: true + ACTIVITI_ES_REST_CLIENT_USERNAME: admin + ACTIVITI_ES_REST_CLIENT_PASSWORD: esadmin +``` + +If you're using an internal PKI, you will need to provide a keystore containing +the certificate chain for the Elasticsearch server as a Kubernetes secret which +must contain the data key `truststore.p12`. + +```yaml +processEngine: + environment: + ... + ACTIVITI_ES_REST_CLIENT_KEYSTORE: /path/to/keystore/truststore.p12 + ACTIVITI_ES_REST_CLIENT_KEYSTORE_TYPE: PKCS12 + ACTIVITI_ES_REST_CLIENT_KEYSTORE_PASSWORD: somesecretpass + volumes: + - name: truststore + secret: + secretName: internal-truststore + volumeMounts: + - name: truststore + readOnly: true + mountPath: /path/to/keystore +```