| title | parent | grand_parent |
|---|---|---|
Upgrades |
Guides |
Helm |
Our helm charts are continuously improved and sometimes arise the need to introduce a breaking change.
To get an overview of the changes in each release, first take a look at the release notes that are available via GitHub Releases.
Here follows a more detailed explanation of any breaking change grouped by version in which they have been released.
- Search Enterprise is now the default search engine when installing Enterprise version. For production it's suggested to use an external elaticsearch index.
.global.ai.enabledhas been removed since adw doesn't need anymore to explicitly enable the AI features.- Postgres database configuration for Sync Service has been moved from
.alfresco-sync-service.postgresqlto.postgresql-sync. Connection details for database can be provided also via an existing configMap/secret in.alfresco-sync-service.database. Message broker configuration has been split from a single secret provided via.alfresco-sync-service.messageBroker.existingSecretNameto two separate existing configMap/secret. More details at sync chart docs - ATS message broker configuration has been split from a single secret provided
via
.alfresco-transform-service.messageBroker.existingSecretNameto two separate existing configMap/secret. More details at ATS chart docs - AI transformer configuration has been refactored, please take a look at the updated AI example docs
Some of the values has been moved to different places, most of the time to better represent the fact it's linked to a specific component/subchart, or that it's a shared/third party component.
The former mail.* values were used to control the configuration of the
outgoing SMTP service in alfresco repository. We consider this mail
configuration an 3rd party architecture component admin provide to Alfresco
platform so any component can send emails. For this reason it's been moved to
global.mail.
email.*values were used to configure Alfresco repository inbound SMTP service
As this configuration details are not considered architecture related (but is
just component config), it's been moved to the alfresco-repository subchart:
alfresco-repository.configuration.smtp.*
imap.*values were used to configure Alfresco repository inbound SMTP service.
As this configuration details are not considered architecture related (but is
just component config), it's been moved to the alfresco-repository subchart:
alfresco-repository.configuration.imap.*
With ACS 7.2 we introduced a mandatory parameter used to pass the secret used
for Solr tracking/querying: global.tracking.sharedsecret. As we also
introduced Alfresco Enterprise search in the mean time and now offer the
ability to use both Solr or Elasticsearch external instance, it became more
sensible to move the whole search related configuration to its own section in
the global context. For that reason the new section global.search.* now
holds the search related connection details. It is not as strict mirroring of
the previous values so please read the next chapter to understand how it works.
As explained above the search configuration has moved. It is now uses a common
section for both Alfresco Search service (Solr based) and Alfresco Search
Enterprise (Elasticsearch based). If you use a fully internal deployment (that's
a setup one should only consider for testing/dev purposes, not prod)
enabling/disabling appropriate components (e.g. enable
alfresco-search-enterprise & disable alfresco-search) should be enough. Of
course if Solr is the chosen search engine, it is still necessary to pass a
shared secret.
Note: A "fully internal deployment" for Alfresco Search Enterprise actually means having both the Alfresco Elasticsearch connectors AND elasticsearch itself inside the cluster.
Passing the Solr shared secret requires the new value: global.search.sharedSecret
Leveraging an external search component can be done using by providing its URL, type and access details. For example, the below values would make the repository use an external elasticsearch instance:
global:
search:
url: https://myopensearch.domain.tld/
flavor: elasticsearch
securecomms: httpsThe metadataKeystore.* where used to pass part of the java keystore related
properties to deal with custom metadata encryption keys. The new
alfresco-repository chart offers a more generic way of dealing with custom
keystore together with a more cohesive way of passing both sensitive and non
sensitive properties. Please refer to alfresco-repository chart keystore
documentation
and the alfresco-repository chart properties
documentation
s3connector.* used to be used for S3 bucket content store configuration. They
have been removed completely from the chart and must now be configured using
one of the mechanisms provided by the alfresco-repository subchart. Also note
that using this values has always required and still requires using a custom
image embedding the Alfresco S3 connector.
Please refer to the alfresco-repository chart documentation
Repository is now deployed as part of an independent subchart. Checkout alfresco-repository for details on how to use that new chart.
This alfresco-content-services chart is now essentially a wrapper of subcharts
which mostly produces secrets and configmaps in order to coordinate them.
Most documentation now link to the chart dedicated to the Alfresco component.
After migrating the AI Transformer chart to the new
alfresco-helm-charts
repository, the associated values have been moved from
.Values.aiTransformer to
.Values.alfresco-ai-transformer.
The previous ooi-service subchart has been renamed to
alfresco-connector-ms365 to better reflect the product name during the
migration to the new
alfresco-helm-charts
repository.
Accordingly to this chart rename, also the related values has been moved from
.Values.ooiService to
.Values.alfresco-connector-ms365.
The previous ms-teams-service subchart has been renamed to
alfresco-connector-msteams to better reflect the product name during the
migration to the new
alfresco-helm-charts
repository.
Accordingly to this chart rename, also the related values has been moved from
.Values.msTeamsService to
.Values.alfresco-connector-msteams.
In previous versions of the charts one could use the values below to tell the charts how to configure Alfresco repo & Share, specifically for security features (CSRF, CORS):
externalHostexternalPortexternalProtocol
These were simple strings and did not allow for multiple domains/URLs to be
used which is exactly one would be expect to do when configuring cross-origin
protections.
This is now possible as we introduce the newer known_urls value.
This value can be either passed to share or repo directly or set in the global
context. Being able to use either the subchart or the global context Allows for
conveniently set this parameter at once for all subcharts or on the contrary
use different values different subcharts if they do not trust the same
domains/URLs.
Global setting:
global:
known_urls:
- https://ecm.domain.tld
- http://app.domain.local:8080/crmTargeted setting:
share:
known_urls:
- https://ecm.domain.tld
repository:
known_urls:
- https://ecm.domain.tld
- http://app.domain.local:8080/crmThe first item in the list will be considered the main domain where alfresco & Share are installed
If you want to use the --set switch of the helm command`, you can still do
it by using either of the syntaxes below to pass a list:
Comma separated list (commas must be escaped):
helm install alfresco-content-services acs --set global.known_urls=https://ecm.domain.tld\,http://app.domain.local:8080/crmIndexed syntax square brackets must be escaped:
helm install alfresco-content-services acs \
--set global.known_urls\[0\]=https://ecm.domain.tld
--set global.known_urls\[1\]=http://app.domain.local:8080/crmNote: We would encourage you to avoid using
--setas much as possible and use--valuesinstead with values stored in yaml files.
Alfresco is now deployed as a separate chart and can be enabled/disabled. In order to do so simply use the value bellow:
share:
enabled: falsealfresco-content-service now offers the ability to fully disable Alfresco
transformation service. It became possible as we have created a dedicated chart:
alfresco-transform-service
This chart is enabled by default in alfresco-content-service but can be
disabled by setting alfresco-transform-service.enabled to false.
This change also incurs a modification of the values.yaml structure.
Previously, all transformer components used to be root objects in the YAML
values definition, and transformmisc was the only one that used to be
"toggle-able". Now all components' values should be placed under the root
alfresco-transform-service node, and each component can be enabled/disable
individually. So for example:
transformmisc:
enabled: true
...Must be turned into:
alfresco-transform-service:
transformmisc:
enabled: true
...and should you want to disable jodconverter transformers you can do so by using:
alfresco-transform-service:
libreoffice:
enabled: true
...Note: the values file contains an Anchor/Aliases to ensure and advertise a way to have some "backward compatibility" with previous values. That mechanism do not propagate beyond the YAML file where it is defined so we strongly recommend updating your
values.yamlto reflect the changes described above.
alfresco-content-services chart has always been the mandatory entrypoint to
deploy Alfresco platform and components. In order to provide more flexibility
we've started an effort of splitting Alfresco components into individual charts
that can be used independently.
That effort is work in progress and we've started by turning the previously embedded subcharts into individual charts hosted in a new repository: alfresco-helm-charts
The associated registry is https://alfresco.github.io/alfresco-helm-charts/
These change comes with some deep modifications of the values structure:
We have introduced resources.request & resources.limits for each Alfresco
component deployment. The purpose is of course to avoid a single component
eating up all of the worker node's resource. Though, the default we provide
might not suit your workload and you MUST review them and align them in you
values in order to make sure your environment runs with appropriate amount of
resource.
Customizing resource allocation follow the generic kubernetes syntax under each component's YAML node. For example for the ACS repo:
repository:
resources:
requests:
cpu: "0.5"
memory: "1000Mi"
limits:
cpu: "1"
memory: "1000Mi"You should focus on the limits to allow for more resource to be allocated to the pods while the requests are mostly present to avoid scheduling the node on too small worker nodes or requesting too much resources than needed.
The following charts benefited from a shift in the way resources are names. We've tried to stick more closely to the Helm provided templates. That impacts the charts in different ways and we advise you review changes for each chart or deploy the new chart somewhere for tests and compare the resource names if you anticipate this change may be a problem for you and need to know about the new names.
The list of charts which had some naming template modifications:
We have changed part of the YAML structure of the values.yaml file.
Some changes should be transparent some other require to align you own values.
alfresco-elasticsearch-connector => alfresco-search-enterprise
alfresco-search => alfresco-search-service
alfresco-admin-app => alfresco-control-center
alfresco-sync-service.syncservice => alfresco-sync-service
The previous alfresco-elasticsearch-connector subchart has been renamed to
alfresco-search-enterprise to better reflect the product name during the
migration to the new
alfresco-helm-charts
repository.
Accordingly to this chart rename, also the related values has been moved from
.Values.alfresco-elasticsearch-connector to
.Values.alfresco-search-enterprise.
The elasticsearch dependency (from elastic.co) has been moved from the main
chart to the new alfresco-search-enterprise, thus the Values has been moved
from .Values.elasticsearch to
.Values.alfresco-search-enterprise.elasticsearch
A default CPU resources requests and limits has been introduced to make sure that Kubernetes scheduler has some more hints on how properly place pods on the available nodes in a cluster.
That could be a breaking change for helm installations on cluster that has less than 10 cpu.
You can fine tune CPU resources for each pod by updating the resources section
that is available for each component in their respective values file,
according to the standard kubernetes resources
management.
For example, in the alfresco-content-services values file you can find:
repository:
replicaCount: 2
resources:
requests:
cpu: "1"
memory: "1500Mi"
limits:
cpu: "4"
memory: "3000Mi"That means that each repository pod will have a reservation of 1 full cpu core
and enables bursting up to 4 cpu cores. You can also reduce the number of
replicas for the components that allows it.
Previous versions of the chart did not use that per-component approach to storage.
Instead, the default behavior was to create a PVC and rely by default on it for
any kind of data to persist). That approach has proven to cause problems and
that's why we're moving away from it.
However if you have already deployed using this approach and want to keep it
(which we don't recommend), you can do so by using the static provisioning approach
and set the existingClaim to the previously created PVC alfresco-volume-claim:
postgresql:
persistence:
existingClaim: alfresco-volume-claimAnother option is to create a new volume and copy data to it from the old
volume bound to the old alfresco-volume-claim.
Details of this process depends on the type of storage and provisioner that
was used during deployment.
If you choose the second - and preferred - method, you'll then need to use
static provisioning method to
create a new volume and then instruct helm to search for a specific volume by
claim name or storageClass. Using storageClass requires creating a new PVC
too, which should reference the PV name to make sure a new volume is not
dynamically created.
Also, applying labels to the PV and corresponding selector to the PVC
helps ensure the storageClass will only pick the intended volume.
Version 5.3.0 changes the way the default persistence is set up for the PostgreSQL database. If you did not customize the database persistance (which was not recommended for serious workloads). Please take a look at this before trying to upgrade.
As of chart version 5.2.0 (ACS 7.2.0) it is now required to set a shared secret for solr and repo to authenticate to each other.
global:
tracking:
auth: secret
sharedsecret: 50m3S3cretTh4t!s5tr0n6If you are deploying ACS version pre 7.2.0 with charts version 5.2.0+, make
sure to set the value below to your values.yml file:
global:
tracking:
auth: noneIf you try to install ACS 7.2.0 and following versions, the configuration below is not supported anymore and you are required to set a shared secret.
ℹ️ Due to protocol and ingress restrictions FTP is not exposed via the Helm chart.
Version 5.0.0 and later of the ACS Helm chart has been updated to be version agnostic, meaning the same chart can now be used to deploy different versions of ACS.
By default the latest version of the chart will always deploy the latest development version of ACS. A set of values files are also provided that can be used to deploy a specific major.minor version.
As the Helm chart no longer deploys a specific version of ACS the
appVersionproperty within the chart is longer be specified.