AWS Partner Network (APN) Blog
Using Amazon OpenSearch Service with Serverless Alfresco Content Services
By WeeMeng Chong, Sr. Partner Solution Architect – AWS
By Alexandre Chapellon, DevOps Manager – Hyland Software
 |
| Hyland Software |
 |
Hyland Software’s Alfresco Content Services (ACS) 7.3 enables enterprises to deliver open, flexible, and highly scalable solutions by providing capabilities for full-featured enterprise content services.
Amazon OpenSearch Service is a managed service from Amazon Web Services (AWS) that lets you run OpenSearch clusters without having to worry about managing, monitoring, and maintaining your infrastructure, or having to build in-depth expertise. Amazon OpenSearch Service provides Elasticsearch database service to Alfresco Search Enterprise.
AWS Fargate is a serverless compute technology used to run containers without having to manage servers. The database service supporting the Alfresco repository is Amazon Aurora Serverless v2, which is available for the PostgreSQL-Compatible Edition.
Together, these products present a powerful yet efficient platform to build your content management system. With serverless computing, infrastructure management tasks like capacity provisioning and patching are handled by AWS, so you can focus on your users.
This post describes a simplistic deployment to show the ease in which Amazon OpenSearch Service is used with Alfresco Content Services and Alfresco Search Enterprise running in Amazon Elastic Kubernetes Service (Amazon EKS) on AWS Fargate. Production-grade deployments that require high availability and durability can be guided by this post. Please contact your AWS and Hyland account teams for assistance in designing a production grade deployment.
Hyland Software is an AWS Competency Partner and AWS Marketplace Seller that enables customers to digitalize their workplaces and fundamentally transform their operations.
Solution Overview
This post uses Hyland’s ACS Helm chart with tweaks for Amazon Elastic File System (Amazon EFS), Amazon MQ, Application Load Balancer (ALB), and AWS Fargate. Further, AWS CloudFormation and eksctl are used to provision the AWS services leveraged in this post.
AWS Command Line Interface (CLI) and kubectl are used for configuration management.
Figure 1 – AWS architecture for Alfresco Content Services solution.
- Alfresco Content Services is deployed onto AWS with AWS CLI, eksctl, kubectl, and AWS CloudFormation.
- Users access Alfresco services through web browsers on their workstations or smartphones.
- Alfresco modules providing enterprise content management functionalities are frontend by Application Load Balancers.
- Alfresco Search Enterprise use connector modules to interact with an Elasticsearch database.
- Amazon OpenSearch Service provides Elasticsearch database functionality for Alfresco Search Enterprise.
- Amazon Aurora provides relational database management system (RDBMS) functionality for ACS.
- Amazon EFS provides filestore functionality for ACS.
- Amazon MQ provides queue messaging functionality for ACS.
- Transformation router provides routing for transformation requests.
- Internal HTTP file sharing services facilitating content transformation services.
Prerequisites
This is a hands-on walkthrough; therefore, this post assumes familiarity with Git, container orchestration with Kubernetes, ACS administration, and general AWS Cloud concepts.
For this walkthrough, you need the following:
- AWS account that has privileges to create resources for the following services:
- Amazon EKS
- AWS Fargate
- AWS Key Management Services (AWS KMS)
- Amazon MQ
- Amazon Aurora Serverless v2 PostgreSQL-Compatible Edition
- Amazon OpenSearch Service
- Amazon EFS
- AWS CloudFormation
- Application Load Balancer
- Amazon Virtual Private Cloud (Amazon VPC)
- Public and private subnets
- Security groups
- ACS Enterprise license enabled with Search Enterprise
- Quay.io account with privileges to pull Alfresco images. Quay.io accounts are provided with either an ACS Enterprise or trial license. An Alfresco Search Enterprise license is required for access to the Elasticsearch connector image; contact your Hyland account team for access.
- Documentation for reference:
Step 1: Install Command Line Tools
On a control host with internet access, install and configure AWS CLI, Docker, kubectl, and eksctl per documented procedure.
Step 2: Deploy Kubernetes Cluster on AWS Fargate with eksctl
Download the reference cluster template to deploy into AWS Availability Zones (AZs) in the ap-southeast-1 region. Update the template with the AZs (two) if needed and the name of your cluster.
This template creates two AWS Fargate profiles for Amazon EKS: fp-acs for the alfresco namespace, and fp-default for kube-system and default namespaces.
Deploy the cluster, replacing myClusterTemplate.yaml with the name of your cluster template.
$ eksctl create cluster -f myClusterTemplate.yaml
It takes about 12 minutes to create the cluster. When eksctl reports the cluster is ready (“EKS cluster yourClusterName in yourRegion region is ready”), create an IAM OIDC identity provider for your cluster, replacing myCluster with the name of the cluster created above.
$ eksctl utils associate-iam-oidc-provider --cluster myCluster --approve
Step 3: Configure the Kubernetes Cluster
A helper script, createFgAlbEfsCsi.sh, is provided. Run the script, replacing clusterRegion with the region that cluster was deployed in, and myCluster with the name of the cluster created above.
This script uses Helm to deploy a Kubernetes storage class for EFS-backed persistent volumes and a Kubernetes ingress class that uses ALBs.
$ curl -s https://github.com/AlfrescoLabs/ServerlessACS-OpenSearch/blob/main/createFgAlbEfsCsi.sh | bash -s clusterRegion myCluster
The Alfresco images required for this install are distributed on Quay.io. Create the Kubernetes secret for Quay.io with the credentials obtained from Hyland.
$ kubectl create secret docker-registry docker-registry-secret \
--docker-server=quay.io --docker-username=YOUR-USERNAME \
--docker-password=YOUR-PASSWORD -n alfresco
Step 4: Create/Retrieve AWS KMS Key
An Amazon OpenSearch Service domain that uses fine-grained access control requires an AWS Key Management Service (AWS KMS) key.
Create the KMS key for the region you will be deploying in; at minimum, specify the account used for CloudFormation deployment in the key as an administrator and a user.
Step 5: Deploy AWS Services with CloudFormation
Download the sample CloudFormation template to configure serverless infrastructure services for this ACS deployment. Deploy the template on the CloudFormation console, updating resource details for your environment.
It takes about 18 minutes for the rollout of the CloudFormation stack. The stack provides:
- One VPC security group for internal components
- Open for all internal connections
- One Amazon MQ broker
- ActiveMQ engine v5.17.2 in a private subnet
- Simple authentication and authorization
- One Amazon Aurora PostgreSQL-Compatible Edition Serverless v2 database server
- Password authentication
- No public access
- One database named alfresco
- One file server in Amazon EFS
- Mount targets in provided private subnets
- One Amazon OpenSearch Service domain
- VPC only access in a private subnet
- Cluster max clause count = 10240 (in advanced cluster setting)
- Fine-grained access control domain access policy
- A master user
After the CloudFormation stack is deployed, record the values in the “Resources” and “Outputs” tabs of the CloudFormation console of your stack. You’ll need the values displayed for the rest of this walkthrough.
Step 6: Create Kubernetes Storage Configurations
Run the createEfsVol.sh script to create the storage configurations for your cluster, passing in the Physical ID of EFSSharedFileStore listed in the “Resources” tab of the above CloudFormation stack to replace fs-aabbbcccddeeffgghh in the example below.
This script statically provisions a persistent volume because dynamic persistent volume provisioning with AWS Fargate nodes cannot currently be used.
$ curl -s https://raw.githubusercontent.com/AlfrescoLabs/ServerlessACS-OpenSearch/main/createEfsVol.sh | bash -s fs-aabbbcccddeeffgghh
Step 7: Use Helm to Create a Kubernetes Template
The 5.3 release of the ACS Helm chart does not account for deployments on AWS Fargate. Instead of having Helm install the chart, use Helm to create a Kubernetes template for deployment so adjustments for Fargate can be made prior to deployment.
Clone Hyland’s ACS deployment Git repository and switch to the v5.3.0 release.
$ git clone https://github.com/Alfresco/acs-deployment.git
$ cd acs-deployment && git checkout tags/v5.3.0
Make a copy of the values.yaml file from the Helm chart and update with values from the above CloudFormation stack, or use the starter values configuration file for ACS 7.3 and replace all of the placeholders (marked with <angle brackets>) with values from the same CloudFormation stack. Name the new values file, 7.3AWSFargatevalues.yaml.
Now, create the Kubernetes template for your environment with Helm.
$ helm dependency build helm/alfresco-content-services
$ helm template --debug --dry-run acs helm/alfresco-content-services /
-n alfresco -f 7.3AWSFargatevalues.yaml > 7.3AWSFargateTemplate.yaml
Note the filename of the generated template is 7.3AWSFargateTemplate.yaml.
Step 8: Patch the Kubernetes Cluster for Fargate and Amazon MQ
Since we’re using an ALB for Fargate instead of the classic load balancer used in the ingresses generated by Helm, these ingresses have to be removed. In the generated template, delete all three kind: Ingress Kubernetes resources.
If you have your own certificate, import it into AWS Certificate Manager (ACM) and get its Amazon Resource Name (ARN). Else, obtain either a private or public certificate from ACM and get its ARN.
Once managed in ACM, the ARN of the certificate can be obtained with the following script; replace MyDomainName with the name of your domain for your Alfresco instance.
$ curl -s https://raw.githubusercontent.com/AlfrescoLabs/ServerlessACS-OpenSearch/main/retrieveCert.sh | bash -s <MyDomainName>
Next, copy the resource template for the ALB into the generated template, replacing the <ARN_Of_Certificate> placeholder with the ARN of your SSL certificate retrieved above.
In the generated template, locate the kind: Service resource for acs-alfresco-cs-share. Insert the following into the metadata.annotations section.
alb.ingress.kubernetes.io/healthcheck-path: /share
alb.ingress.kubernetes.io/success-codes: 200,302
The patched resource should look like this sample.
Step 9: Create Kubernetes Secret for ACS License
Follow the procedure provided by Hyland to create the Kubernetes secret for your ACS license. Note the ACS_NAMESPACE used in the Helm generated template is alfresco rather than acs.
Step 10: Deploy ACS on EKS Fargate Launch Type
With the Kubernetes template patched for AWS Fargate and Amazon MQ, deploy the template onto Amazon EKS.
$ kubectl -n alfresco apply -f 7.3AWSFargateTemplate.yaml
It takes about 20 minutes to deploy the ACS and for its initialization process to complete. Grab a coffee, sit back, and take a break.
Step 11: Update Forwarding Path in DNS
Your domain name system (DNS) will need the address of the ALB to forward to. Use the script below to obtain the ALB’s IP for your DNS.
$ DNSName=$(aws elbv2 describe-load-balancers --query \ 'LoadBalancers[?starts_with(LoadBalancerName,`acs-alfresco-alb`) == `true`]'\ | jq -r .[].DNSName) && dig +short $DNSName
Step 12: Ingest Documents
With your browser open, access the Alfresco Digital Workspace interface at https://acs.yourDNSname.
Import documents into your Alfresco repository with Alfresco Digital Workspace. Note the default configuration provided by Hyland does not full-text index documents larger than 25 megabytes. This limit can be raised through additional configuration.
Step 13: Search Documents
Now you can search for documents! Note that documents ingested may not be immediately available to be searched. If you aren’t able to locate your documents through search, try again in a little while.
Cleaning Up
To avoid incurring future charges, delete the AWS CloudFormation stacks, certificates, and Certificate Authority (if not needed anymore), and schedule the AWS KMS key for deletion.
Conclusion
This post walks through the salient points in configuring Alfresco Content Services and Alfresco Search Enterprise to run in AWS Fargate and use Amazon OpenSearch Service as the provider for Elasticsearch.
The sample code, software libraries, command line tools, proofs of concept, templates, scripts, or other related technology (including any of the foregoing that are provided by AWS personnel) is provided to you as AWS Content under the AWS Customer Agreement, or the relevant written agreement between you and AWS (whichever applies). You should not use this AWS Content in your production accounts, or on production or other critical data.
You are responsible for testing, securing, and optimizing the AWS Content, such as sample code and/or template, as appropriate for production-grade use based on your specific quality control practices and standards. Deploying AWS Content may incur AWS charges for creating or using AWS chargeable resources, such as running AWS Fargate or using Amazon EFS storage.
Learn more about Hyland Software on AWS Marketplace.
.
.
Hyland Software – AWS Partner Spotlight
Hyland Software is an AWS Partner that enables customers to digitalize their workplaces and fundamentally transform their operations.
Contact Hyland Software | Partner Overview | AWS Marketplace