diff --git a/README.md b/README.md deleted file mode 100644 index b5c3ad15..00000000 --- a/README.md +++ /dev/null @@ -1,36 +0,0 @@ -# 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). - -## 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: - -* https://github.com/helm/chart-testing -* 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: `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 -``` - -### PR workflow - -Each time a PR is raised, `ct` automatically detect 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 via a manually triggered [GHA workflow](https://github.com/Alfresco/alfresco-helm-charts/actions/workflows/updatecli.yaml). - diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..81d8cfc3 --- /dev/null +++ b/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). diff --git a/docs/getting-started-with-alfresco-charts.md b/docs/getting-started-with-alfresco-charts.md new file mode 100644 index 00000000..307a55a0 --- /dev/null +++ b/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.