Skip to content

Commit

Permalink
OPSEXP-2242: some doc cleanup (#1024)
Browse files Browse the repository at this point in the history
  • Loading branch information
@alxgomz
alxgomz authored Oct 4, 2023
1 parent 82e28c0 commit 74a9007
Show file tree
Hide file tree
Showing 10 changed files with 39 additions and 300 deletions.
49 changes: 3 additions & 46 deletions docs/helm/examples/alf_license.md
View file
Original file line number Diff line number Diff line change
@@ -1,47 +1,4 @@
# Deploy Alfresco Content Services with the ability to manage licenses
# Documentation moved

Alfresco content repository Docker images come with an embedded license which last only 2 days. If you've built a custom image, it may have a one year license but in order to change it you would need to build a new image.
You can configure the ACS Helm chart so the license is instead read from a kubernetes secret so that when it's time to renew the license the only thing you need to do is to update that secret as needed.

This relies on 2 steps:

* creating a secret to hold the license
* configuring the chart to use that secret

## Create a kubernetes secret to store the license

Make sure your license available is readable and you have appropriate kubernetes access in order to create a secret in the ACS namespace where you want to deploy the helm release.

```bash
ACS_NAMESPACE=acs
LIC64=$(base64 < ~/Downloads/Alfresco-ent72-foobar.lic | tr -d '\n')
cat <<EOF | kubectl -n $ACS_NAMESPACE apply -f -
apiVersion: v1
kind: Secret
metadata:
name: acslicense
type: Opaque
data:
alfresco.lic: $LIC64
EOF
```

## Configure the chart to leverage that secret

In the chart value file add the following:

```yaml
repository:
licenseSecret: acslicense
```
> You can obtain a license file for your Alfresco enterprise subscription from the [Hyland Community portal](https://community.hyland.com/)
## Applying a new license
Before your license expires you will want to apply a new one. It's actually very easy do to so. All you need to do is overwrite the secret you created on previous deployment.
You can use the exact same command just replacing the license file with the new one.
> Secret update will trigger pods update. The default update strategy with repository pods is set to `Recreate`.
> As a consequence updating the license will trigger a downtime. You might want to switch the repository deployment to a smoother update strategy by removing `Recreate` setting.
> See [our main chart doc](/helm/alfresco-content-services/README.md) for details on `RollingUpdate` strategy.
Please now refer to the [alfresco-repository chart
documentation](https://github.com/Alfresco/alfresco-helm-charts/blob/main/charts/alfresco-repository/docs/enterprise-license.md)
15 changes: 3 additions & 12 deletions docs/helm/examples/custom-metadata-keystore.md
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,4 @@
# Alfresco Content Services Deployment With Custom Metadata Keystore
# Documentation moved

Alfresco content repository Docker images comes with a pre-created default keystore that contains a secret key. See more information in [docs.alfresco.com](https://docs.alfresco.com/6.2/concepts/alf-keystores.html) and [Dockerfile](https://github.com/Alfresco/acs-packaging/blob/master/docker-alfresco/Dockerfile#L81-L85).

It is recommended to generate a new keystore in production systems. It can be mounted to the content-repository docker image to this location "/usr/local/tomcat/shared/classes/alfresco/keystore/". If the standard names of the keystore and the key are used, it is only required to change password values in [values.yaml](../../../helm/alfresco-content-services/values.yaml):

```yaml
metadataKeystore:
keystorePassword: ""
keyPassword: ""
```
Otherwise, please refer to the full list of configuration options in [docs.alfresco.com](https://docs.alfresco.com/6.2/concepts/keystore-config.html)
Please now refer to the [alfresco-repository chart
documentation](https://github.com/Alfresco/alfresco-helm-charts/blob/main/charts/alfresco-repository/docs/keystores.md)
94 changes: 3 additions & 91 deletions docs/helm/examples/email-enabled.md
View file
Original file line number Diff line number Diff line change
@@ -1,92 +1,4 @@
# Alfresco Content Services Deployment with Inbound & Outbound SMTP Configuration
# Documentation moved

This example demonstrates how to enable Inbound and Outbound email when installing the ACS Helm chart.

## Prerequisites

Follow the [EKS deployment](../eks-deployment.md) guide up until the [ACS](../eks-deployment.md#acs) section, once the docker registry secret is installed return to this page.

## Deploy ACS Helm Chart With Email Server Enabled

Currently, the ingress-nginx does not support tcp/udp services due to kubernetes limitations and the workaround is to expose the TCP (for example smtp(s), imap(s)) to be accessible from outside over internet, a kubernetes Service LoadBalancer is required. This means inbound email need to be sent using this Service LoadBalancer address which is serving tcp traffic. This may means there is an overhead of an extra L4 LoadBalancer cost. This is purely due to current limitations on Kubernetes for TCP/UDP services and not related to ACS helm setup.

So, for example if your ACS Helm chart is enabled with Inbound/Outbound email in domain `*.example.com`, then the service endpoints would be:

- `myacs.example.com` - For general Alfresco, Share and Digital Workspace endpoints
- `smtps-myacs.example.com` - For sending emails to ACS smtp(s) server (for example port: 1125 (smtps), 1144(imaps))

It is recommended to enable TLS while configuring SMTP(s) and IMAP(s) configuration. If TLS is enabled for inbound email, then the helm chart expects the TLS certificate as a Secret before installing the chart. This secret name is passed on as a parameter with helm chart installation to be used for inbound email with TLS and repository will create keystore and truststore accordingly from the provided SSL certificates.

For example, if your ACS email server name is `smtps-myacs.example.com` and your SSL certificates (self signed or signed) are `cert.pem`, `fullchain.pem` and `privkey.pem` run the following command to create a kubernetes TLS secret:

```bash
kubectl create secret tls your-cert-secret --key privkey.pem --cert fullchain.pem --namespace=alfresco
```

Deploy the latest version of ACS Enterprise by running the command below (replacing `YOUR-DOMAIN-NAME` with the hosted zone you created and replacing the email values appropriately). For the full list of available options please refer to the table of [configuration options](../../../helm/README.md#configuration).

```bash
helm install acs alfresco/alfresco-content-services \
--set repository.persistence.enabled=true \
--set repository.persistence.storageClass="nfs-client" \
--set filestore.persistence.enabled=true \
--set filestore.persistence.storageClass="nfs-client" \
--set global.known_urls=https://acs.YOUR-DOMAIN-NAME \
--set global.alfrescoRegistryPullSecrets=quay-registry-secret \
--set global.tracking.sharedsecret=$(openssl rand -hex 24) \
--set mail.host="smtp.gmail.com" \
--set mail.from.default="[email protected]" \
--set mail.username="[email protected]" \
--set mail.password="somepassword" \
--set mail.protocol=smtps \
--set mail.smtp.auth=true \
--set mail.smtps.auth=true \
--set email.server.enabled=true \
--set email.server.auth.enabled=true \
--set email.server.enableTLS=true \
--set email.server.domain=smtps-myacs.example.com \
--set email.inbound.unknownUser="[email protected]" \
--set email.ssl.secretName=your-cert-secret \
--set imap.server.enabled=true \
--set imap.server.imap.enabled=true \
--set imap.server.imaps.enabled=true \
--atomic \
--timeout 10m0s \
--namespace=alfresco
```

> NOTE: If you are using GMail or Yahoo as the outbound email server, your application's attempts to send outgoing emails may be blocked by the email providers due to their security policies as if it considers the authentication attempts to be suspicious. When this happens, you will receive a security alert at the corresponding email address. To proceed, you will need to manually confirm the validity of the authentication attempt before the email provider will permit the application to send outbound emails. For more information on [Less secure apps & your Google Account](https://support.google.com/accounts/answer/6010255).
## Exposing Email Service

Ingress-nginx currently does not support TCP or UDP services. The helm chart will expose SMTP service as a LoadBalancer (it creates a new AWS ELB). This LoadBalancer/ELB information can be obtained by running the following command:

```bash
kubectl get services `kubectl get services --namespace=alfresco | grep email | awk '{print $1}'` --namespace=alfresco
```

This will produce an output similar to the one below, the ELB DNS name can be found in the "EXTERNAL-IP" column.

```bash
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
alert-fly-alfresco-cs-email LoadBalancer 100.XX.33.188 a1dXXXXXab11eaac6702XXXf87b-XXXXXXXXXX.eu-west-1.elb.amazonaws.com 1125:30554/TCP 2d
```

## Test Email Service

1. Use Route53 to register a more friendly name for the ELB DNS name retrieved in the previous section, for example `smtps-myacs.example.com`.

2. Test the communication using Telnet:

```bash
$ telnet smtps-myacs.example.com 1125
Trying 34.249.150.165...
Connected to smtps-myacs.example.com.
Escape character is '^]'.
220 smtps-myacs.example.com ESMTP SubEthaSMTP 3.1.7
```

## References

- [Alfresco Configuring email](https://docs.alfresco.com/content-services/latest/admin/)
- [Kubernetes Ingress-nginx Exposing TCP and UDP services](https://github.com/kubernetes/ingress-nginx/blob/master/docs/user-guide/exposing-tcp-udp-services.md#exposing-tcp-and-udp-services)
Please now refer to the [alfresco-repository chart
documentation](https://github.com/Alfresco/alfresco-helm-charts/blob/main/charts/alfresco-repository/docs/email.md)
76 changes: 18 additions & 58 deletions docs/helm/examples/search-services.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,18 +13,20 @@ container based environments. Some are mentioned bellow:
workload scheduling or the ephemeral nature of containers in general.

For that reason we recommend for production environments to install Search
services alongside the Kubernetes cluster and config the Helm charts to not
services alongside the Kubernetes cluster and configure the Helm charts to not
deploy it and instead point the repository to the external one.

## Configuring Helm chart

Bellow we explain how to configure the Helm chart to point the repository to an
external Solr instance.
Below we explain how to configure the Helm chart to point the repository to a
Solr instance outside of the kubernetes cluster.

Installing Solr instance(s) is out of the scope of this document, but it can be
done following the [Search service documentation](https://docs.alfresco.com/insight-engine/latest/install/options/#install-without-mutual-tls---http-with-secret-word-zip),
done following the [Search service
documentation](https://docs.alfresco.com/insight-engine/latest/install/options/#install-without-mutual-tls---http-with-secret-word-zip),
or by using the Ansible playbook (replication setup require an additional
load-balancer), as explained [here](https://github.com/Alfresco/alfresco-ansible-deployment/blob/master/docs/search-services-deployment-guide.md).
load-balancer), as explained
[here](https://github.com/Alfresco/alfresco-ansible-deployment/blob/master/docs/search-services-deployment-guide.md).

On the chart side you need to:

Expand All @@ -34,14 +36,13 @@ On the chart side you need to:

```yaml
global:
tracking:
auth: secret
sharedsecret: dummy
search:
url: http://internal-load-balancer-ac3a091cb.eu-west-1.elb.amazonaws.com/solr
flavor: solr6
securecomms: secret
sharedSecret: d0ntT3llAny0n3
alfresco-search:
enabled: false
external:
host: internal-load-balancer-ac3a091cb.eu-west-1.elb.amazonaws.com
port: 80
```
In this example an internal load balancer is created and aims a target group
Expand Down Expand Up @@ -73,7 +74,7 @@ api, so it doesn't make much sense to use external access.

Follow the [EKS deployment](../eks-deployment.md) guide up until the
[ACS](../eks-deployment.md#acs) section, once the docker registry secret is
installed return to this page.
installed come back here.

Deploy the latest version of ACS Enterprise by running the command below
(replacing `YOUR-DOMAIN-NAME` with the hosted zone you created previously and
Expand All @@ -83,57 +84,16 @@ previous section).

```bash
helm install acs alfresco/alfresco-content-services \
--set persistence.enabled=true \
--set persistence.storageClass.enabled=true \
--set persistence.storageClass.name="nfs-client" \
--set alfresco-repository.persistence.enabled=true \
--set alfresco-repository.persistence.storageClass.enabled=true \
--set alfresco-repository.persistence.storageClass.name="nfs-client" \
--set global.known_urls=https://acs.YOUR-DOMAIN-NAME \
--set global.tracking.sharedsecret=dummy \
--set global.search.securecomms=none \
--set global.alfrescoRegistryPullSecrets=quay-registry-secret \
--set alfresco-search.ingress.enabled=true \
--set alfresco-search.ingress.annotations.nginx\.ingress.kubernetes\.io/whitelist-source-range=10.0.0.0/8 \
--set alfresco-search.ingress.basicAuth="YOUR-BASIC-AUTH" \
--set alfresco-search.ingress.whitelist_ips="YOUR_IPS" \
--atomic \
--timeout 10m0s \
--namespace=alfresco
```

### Upgrade ACS Helm Chart With Search External Access

If you've previously deployed ACS where external search access was disabled
(the default) you can run the following `helm upgrade` command to enable
external access for `/solr` (replacing `YOUR-BASIC-AUTH` and `YOUR-IPS` with
the encoded basic authentication string and list of whitelisted IP addresses
you prepared in the "Prepare Data" section):

```bash
helm upgrade acs alfresco/alfresco-content-services \
--set alfresco-search.ingress.enabled=true \
--set alfresco-search.ingress.basicAuth="YOUR-BASIC-AUTH" \
--set alfresco-search.ingress.whitelist_ips="YOUR_IPS" \
```

> **Note:** There are known issues when upgrading a Helm chart relating to Helm
> cache.

- `https://github.com/Kubernetes/helm/issues/3275`
- `https://github.com/Kubernetes/helm/issues/1193`
- `https://github.com/Kubernetes/helm/pull/4146`

If your `helm upgrade` fails due to any of these example errors:

```bash
Error: UPGRADE FAILED: no Secret with the name "nosy-tapir-alfresco-search-solr" found
(or)
Error: UPGRADE FAILED: no Ingress with the name "nosy-tapir-alfresco-search-solr" found
```

Then, simply delete that resource. Below is an example:

```bash
kubectl delete secret nosy-tapir-alfresco-search-solr --namespace=alfresco
(or)
kubectl delete ingress nosy-tapir-alfresco-search-solr --namespace=alfresco
```

And re-try above Upgrade ACS Helm Chart steps which will also re-create the
above deleted resource.
27 changes: 4 additions & 23 deletions docs/helm/security.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,32 +23,13 @@ solutions are:
* [Mozilla SOPS](https://github.com/mozilla/sops)
* [Sealed secrets](https://github.com/bitnami-labs/sealed-secrets)

In the ACS Helm charts, you will find the possibility to provide such secrets in
an alternative way. Instead of providing credentials as values, it is possible
to provide a Kubernetes secret name, setting the appropriate
`existingSecretName` value available in the different charts. These Kubernetes
Secrets need to be created before attempting the Helm install and would contain
the necessary secrets.

For example, you can provide the `repository.adminPassword` value as a secret by
creating:

```sh
kubectl -n your-namespace create secret generic "repo-secret" \
--from-literal=REPO_ADMIN_PASSWORD=209c6174da490caeb422f3fa5a7ae634
```

And by setting `existingSecretName` to `repo-secret` instead of
`repository.adminPassword`.

> Note: Such Kubernetes Secret needs to live within the same namespace you
> plan to deploy to.
Reference the autogenerated README.md in each chart to understand which secrets
can be provided using existing Kubernetes Secrets:

* [alfresco-content-services](../../helm/alfresco-content-services/README.md)
* [alfresco-repository](https://github.com/Alfresco/alfresco-helm-charts/blob/main/charts/alfresco-repository/docs/repository-properties.md)
* [activemq](https://github.com/Alfresco/alfresco-helm-charts/blob/main/charts/activemq/README.md)
* [alfresco-search-enterprise](https://github.com/Alfresco/alfresco-helm-charts/blob/main/charts/alfresco-search-enterprise/README.md)
* [alfresco-search](../../helm/alfresco-content-services/charts/alfresco-search/README.md)
* [alfresco-search](https://github.com/Alfresco/alfresco-helm-charts/blob/main/charts/alfresco-search-service/README.md)
* [alfresco-transform-service](https://github.com/Alfresco/alfresco-helm-charts/blob/main/charts/alfresco-transform-service/README.md)
* [alfresco-share](https://github.com/Alfresco/alfresco-helm-charts/blob/main/charts/alfresco-share/README.md)
* [alfresco-sync-service](https://github.com/Alfresco/alfresco-helm-charts/blob/main/charts/alfresco-sync-service/README.md)
9 changes: 0 additions & 9 deletions helm/alfresco-content-services/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -192,7 +192,6 @@ Please refer to the [documentation](https://github.com/Alfresco/acs-deployment/b
| alfresco-transform-service.transformrouter.image.repository | string | `"quay.io/alfresco/alfresco-transform-router"` | |
| alfresco-transform-service.transformrouter.image.tag | string | `"3.1.0-M1"` | |
| alfresco-transform-service.transformrouter.replicaCount | int | `2` | |
| apiexplorer | object | `{"ingress":{"path":"/api-explorer"}}` | Declares the api-explorer service used by the content repository |
| database.configMapName | string | `"alfresco-infrastructure"` | Name of the secret managed by this chart |
| database.driver | string | `nil` | Postgresql jdbc driver name ex: org.postgresql.Driver. It should be available in the container image. |
| database.existingSecretName | string | `nil` | An existing secret that contains DATABASE_USERNAME and DATABASE_PASSWORD keys. When using embedded postgres you need to also set `postgresql.existingSecret`. |
Expand Down Expand Up @@ -245,14 +244,6 @@ Please refer to the [documentation](https://github.com/Alfresco/acs-deployment/b
| postgresql.primary.resources.limits.memory | string | `"8Gi"` | |
| postgresql.primary.resources.requests.cpu | string | `"500m"` | |
| postgresql.primary.resources.requests.memory | string | `"1Gi"` | |
| repository.adminPassword | string | `"209c6174da490caeb422f3fa5a7ae634"` | Administrator password for ACS in NTLM hash format to set at bootstrap time |
| repository.edition | string | `"Enterprise"` | |
| repository.existingSecretName | string | `nil` | An existing secret that contains REPO_ADMIN_PASSWORD as an alternative for `repository.adminPassword` value |
| repository.extraLogStatements | object | `{}` | Provide additional log statements by adding classes and/or packages in a key:value maner org.alfresco.repo.content.transform.TransformerDebug: debug |
| repository.licenseSecret | string | `nil` | The name of the secret holding the ACS repository license if any. it must be contained within a `data['*.lic']` property For details on how to manage license, see: https://github.com/Alfresco/acs-deployment/blob/master/docs/helm/examples/alf_license.md |
| repository.replicaCount | int | `2` | |
| repository.service.externalPort | int | `80` | |
| repository.strategy.type | string | `"Recreate"` | |
| s3connector.config.bucketLocation | string | `nil` | |
| s3connector.config.bucketName | string | `nil` | |
| s3connector.enabled | bool | `false` | Enable the S3 Connector For a full list of properties on the S3 connector see: https://docs.alfresco.com/s3connector/references/s3-contentstore-ref-config-props.html |
Expand Down
2 changes: 1 addition & 1 deletion helm/alfresco-content-services/templates/NOTES.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ You can access all components of Alfresco Content Services using the same root a
Content: {{ $alfurl }}/alfresco
Share: {{ $alfurl }}/share
API-Explorer: {{ $alfurl }}/api-explorer
{{- if eq .Values.repository.edition "Enterprise" }}
{{- if index .Values "alfresco-digital-workspace" "enabled" }}
Alfresco Digital Workspace: {{ $alfurl }}/workspace/
{{- end }}
{{- if index .Values "alfresco-search" "ingress" "enabled" }}
Expand Down
Loading

0 comments on commit 74a9007

Please sign in to comment.