From 76da749051733227f6e3eb38423478a56f1eeb2e Mon Sep 17 00:00:00 2001 From: Alexandre Chapellon Date: Fri, 27 Oct 2023 11:26:07 +0200 Subject: [PATCH] provide example based doc to compose with alfresco charts --- docs/README.md | 52 ++++-- docs/getting-started-with-alfresco-charts.md | 177 +++++++++++++++++++ 2 files changed, 218 insertions(+), 11 deletions(-) create mode 100644 docs/getting-started-with-alfresco-charts.md diff --git a/docs/README.md b/docs/README.md index b5c3ad15b..81d8cfc34 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,36 +1,66 @@ # alfresco-helm-charts -⚠️⚠️⚠️ This repo represent an ongoing effort to make the existing [Alfresco Helm Charts](https://github.com/Alfresco/acs-deployment/tree/master/helm/alfresco-content-services) more independent and reusable. Please continue to refer to the parent [acs-deployment](https://github.com/Alfresco/acs-deployment) repository for [docs](https://github.com/Alfresco/acs-deployment/tree/master/docs/helm) and [issues](https://github.com/Alfresco/acs-deployment/issues). +This repository aims at delivering independent and lightweight +[Helm](https://helm.sh) charts for Alfresco Content Services platform that can +be used as building blocks by devops teams to build the Content Services +platform that match the organization needs. + +⚠️ The existing [Alfresco Helm +Charts](https://github.com/Alfresco/acs-deployment/tree/master/helm/alfresco-content-services) +remains available and has been updated to leverage charts hosted in this +repository. + +If you want to understand what are the principles to leverage in order to build +on top of Alfresco components' chart please refer to the +[getting-started-with-alfresco-charts](./getting-started-with-alfresco-charts.md) + +Each individual chart has its own documentation page that's available in the +chart directory in [charts/](../charts). There are the values available for +each of them. ## Development -This repository follows the [helm/charts-repo-actions-demo](https://github.com/helm/charts-repo-actions-demo) template, that support the testing and the release of helm charts with the help of two tools: +This repository follows the +[helm/charts-repo-actions-demo](https://github.com/helm/charts-repo-actions-demo) +template, that support the testing and the release of helm charts with the help +of two tools: -* https://github.com/helm/chart-testing -* https://github.com/helm/chart-releaser +* [Helm chart testing](https://github.com/helm/chart-testing) +* [Helm chart releaser](https://github.com/helm/chart-releaser) -In order to install all the tools required for development on MacOS via [Homebrew](https://brew.sh), run: `brew bundle install` +In order to install all the tools required for development on MacOS via +[Homebrew](https://brew.sh), run: `brew bundle install` -To setup [pre-commit](https://github.com/pre-commit/pre-commit), run: `pre-commit install` +To setup [pre-commit](https://github.com/pre-commit/pre-commit), run: + +```shell +pre-commit install +``` To install required helm plugins: ```shell helm plugin install https://github.com/jtyr/kubeconform-helm --version v0.1.12 -helm plugin install https://github.com/vbehar/helm3-unittest --version v1.0.16 +helm plugin install https://github.com/helm-unittest/helm-unittest --version v0.3.4 ``` ### PR workflow -Each time a PR is raised, `ct` automatically detect which charts has been changed and run for them: +Each time a PR is raised, `ct` automatically detects which charts has been +changed and run for them: * linter * unittest * integration tests on KinD -Once a PR that contains a chart version bump is merged, the main workflow will release each version that has not yet released. Each chart release will trigger the creation of git tag, a GitHub release with packages attached and the update of the charts registry index. +Once a PR that contains a chart version bump is merged, the main workflow will +release each version that has not yet released. Each chart release will trigger +the creation of git tag, a GitHub release with packages attached and the update +of the charts registry index. ### Update dependencies -There is an initial support for bumping charts dependencies with updatecli via a manually triggered [GHA workflow](https://github.com/Alfresco/alfresco-helm-charts/actions/workflows/updatecli.yaml). - +There is an initial support for bumping charts dependencies with +[Updatecli](https://www.updatecli.io/) via a manually triggered +[GHA +workflow](https://github.com/Alfresco/alfresco-helm-charts/actions/workflows/updatecli.yaml). diff --git a/docs/getting-started-with-alfresco-charts.md b/docs/getting-started-with-alfresco-charts.md new file mode 100644 index 000000000..45d1f89c2 --- /dev/null +++ b/docs/getting-started-with-alfresco-charts.md @@ -0,0 +1,177 @@ +# Building your Content platform architecture with Alfresco charts + +## The alfresco-common library chart + +Alfresco charts depend on a common library chart called +[alfresco-common](../charts/alfresco-common). This chart provides a set of +[named templates](https://helm.sh/docs/chart_template_guide/named_templates) +one can use in order to build his own content platform chart. + +Named templates are similar to functions in a programing language expect they +can only return strings and always take a single argument (which can be an +object). +For example the [URL helper](../charts/alfresco-comon/templates/_helper-url.tpl) +file provides functions to extract vairous elements from a given URL. +For example: + +* `{{ template "alfresco-common.url.scheme" "https://hub.alfresco.com/" }}` + will return "https" +* `{{ template "alfresco-common.url.port" "https://hub.alfresco.com/" }}` will + return "443" + +Check out the dedicated Chart documentation to get a more comprehensive list of +named templates the chart offers. + +## Alfresco components charts + +The individual Alfresco components' chart are meant to be configurable and +reusable. They do not provide a working system on their own and need to be +either used from an "umbrella chart" or be given additional details about +other components they interact with in order to actually deliver the service +they are meant to deliver. +For example the `alfresco-repository` chart needs to have a database to +initialize its content repository. + +This document explains what are the options you can leverage to "pipe" an +Alfresco chart with another or with an external service. + +### Understanding the Alfresco Content platform + +Before you begin, make sure you do understand the Alfresco Content platform and +its components so you know exactly what you need or do not need. + +⚠️TODO: create chart diagram showing dependencies and level of dependencies + +### Creating your Alfresco platform + +There are numerous ways to create your own Alfresco deployment and the +component charts hosted in this repository can be used as building blocks for +this purpose. Depending on preferences you may want to use +[Terraform](https://www.terraform.io/), +[Kustomize](https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/helmcharts/) +or simply wrap the component charts into an "umbrella chart". + +Here we'll focus on the later option but the same configuration principles +apply to other methods. + +In the example below we'll go through the process of creating a custom chart in +order to deploy a simple content platform made of: + +* Alfresco content repository +* A database that hosted outside of the kubernetes cluster +* Alfresco Enterprise search service +* An elasticsearch cluster hosted as a kubernetes workload + +#### Declaring chart as dependency + +[Helm provides a mechanism to declare +dependencies](https://helm.sh/docs/helm/helm_dependency/) and re-use existing +charts. + +We'll start by initializing a chart and declare the dependency to the +[alfresco-repository](../charts/alfresco-repository) chart. + +```sh +helm create myecmplatform && cd $_ +``` + +Edit the `Chart.yaml` to give the chart a sensible description, a version and +optionally specify the version of your content platform. Then declare the +dependency as shown below: + +```yaml +dependencies: + - name: alfresco-repository + version: 0.1.0 + repository: https://alfresco.github.io/alfresco-helm-charts/ + alias: repo +``` + +> In the example above we use `repo` as an alis so any value in our chart that +lives under the `$.repo` YAML path will actually be passed to the +`alfresco-repository` chart. In other words, values documented for the +`alfresco-repository` chart such as `replicaCount` will be used from your chart +as `repo.replicaCount`. + +#### Configuring the chart + +Now we need to let the repository where it can find its database. +When it comes to configuring a chart so it can reach another component of the +platform, the Alfresco component charts lets you do that in 2 different ways: + +* Using regular values +* Using kubernetes config resources (configMap or secret) + +#### Configuring database using values + +First thing to do is to check the chart's [values +documentation](../charts/alfresco-repository/README.md). There, we can see the +database configuration can be done using the `configuration.db` element in our +`values.yaml` file as shown below: + +```yaml +repo: + configuration: + db: + url: jdbc:postgresql//db.ecm.infra.local/alfresco + username: ecmdaouser + password: ecmdaopass +``` + +#### Configuring database using kubernetes resources + +When using kubernetes resources we will want to differentiate configuration +details which are sensitive and which are not. The former will be stored in +[configMap](https://kubernetes.io/docs/concepts/configuration/configmap/), +while the later would use +[secret](https://kubernetes.io/fr/docs/concepts/configuration/secret/). + +That means here we'll use a configMap to set store the database URL while +credentials would live in a secret. That concretely translate into the +following kubernetes resources: + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + labels: + app.kubernetes.io/instance: myEcmReleaseName + app.kubernetes.io/name: Alfresco-content-platform + app.kubernetes.io/version: 1.0.0 + name: ecm-database-location + namespace: myecm +data: + MY_ECM_DB_URL: jdbc:postgresql://db.ecm.infra.local/alfresco +``` + +```yaml +apiVersion: v1 +kind: Secret +metadata: + labels: + app.kubernetes.io/instance: myEcmReleaseName + app.kubernetes.io/name: Alfresco-content-platform + app.kubernetes.io/version: 1.0.0 + name: ecm-database-credentials + namespace: myecm +data: + MY_ECM_DB_USER: c2NvdHQ= + MY_ECM_DB_PASS: dGlnZXI= +``` + +Now we need to let the `alfresco-repository` chart where to find this: + +```yaml +repo: + configuration: + db: + existingConfigMap: + name: ecm-database-location + keys: + url: MY_ECM_DB_URL + existingSecret: + name: ecm-database-credentials + keys: + username: MY_ECM_DB_USER + password: MY_ECM_DB_PASS +```