OPSEXP-2043: document platform composition using charts (#137)

Co-authored-by: Giovanni Toraldo <[email protected]>

docs/README.md

@@ -0,0 +1,66 @@
+# alfresco-helm-charts
+
+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:
+
+* [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`
+
+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/helm-unittest/helm-unittest --version v0.3.4
+```
+
+### PR workflow
+
+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.
+
+### Update dependencies
+
+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).

docs/getting-started-with-alfresco-charts.md

@@ -0,0 +1,188 @@
+# 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 reusable functions that can only return strings and always
+take a single argument, which eventually can be an object. For example the [URL
+helper](../charts/alfresco-comon/templates/_helper-url.tpl) file provides
+functions to extract various 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 integrating an ACS content
+platform made of:
+
+* Alfresco content repository
+* A database that hosted outside of the kubernetes cluster
+
+> Below example also present using an "unmbrella" Helm chart but most of the
+> same approach is applicable to other deployment method as explained above.
+
+#### 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 alias 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
+  MY_ECM_DB_DRIVER: org.postgresql.Driver
+```
+
+```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=
+```
+
+> For example, if you're creating this confgimap using a wrapping Helm chart,
+> you can reuse a templating function provided by the
+> [alfresco-repository](../charts/alfresco-repository/templates/_helpers-database.tpl)
+> chart `alfresco-repository.db.cm`
+
+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
+        driver: MY_ECM_DB_DRIVER
+      existingSecret:
+        name: ecm-database-credentials
+      keys:
+        username: MY_ECM_DB_USER
+        password: MY_ECM_DB_PASS
+```
+
+> If you used the templating function mentionned above and provided by the
+> subchart the keys would be different than the ondes mentionned in the example
+> above. Actually the function  would render teh default keys so it's not needed
+> to set them.