AWS terraform

This is the documentation for how to use our Terraform for AWS to set up Cobrowse Enterprise in your cloud.

Initial Setup

Make sure you have installed (on your local machine) the required tools to manage and deploy the Cobrowse infrastructure to AWS. You'll need these installed before running the setup scripts:

• Terraform

• NodeJS – at least minimum LTS version

• AWS CLI

• kubectl

You'll also need an AWS account with credentials available to the setup script through the environment. This is most easily managed via the official AWS cli tools.

Installation steps

1. Choose your database

You can choose between MongoDB and AWS DocumentDB as your data storage for Cobrowse Enterprise.

Using MongoDB

We do not provide MongoDB as part of the Terraform environment. We recommend using a hosted service such as MongoDB Atlas. They have a range of certifications required by many enterprises with compliance requirements. Alternatively, you can run your own MongoDB cluster and manage the deployment and backups yourself.

When using MongoDB, the Cobrowse setup process will ask for a connection URL containing the address and authentication information for your MongoDB cluster.

Using AWS Document DB

If you wish to use AWS DocumentDB, you don't have to manually create a storage cluster. The Cobrowse Terraform environment will create the cluster and configure it into the application for you. You will have an option during the automated setup process to choose an AWS-managed DocumentDB database cluster.

Document DB backups and management are supported directly by AWS. It's recommended that you subscribe to an AWS Business (or better) support package to ensure you have support for your data and backups.

2. Create an S3 bucket

Terraform will be configured to save the state of the resources it creates to an S3 bucket. This bucket must be created manually. Its access should be completely private as the terraform state may contain sensitive information.

See the AWS documentation on how to create a bucket if you are unsure about how to do this.

3. Generate the config directory

We have provided a small command line utility to help you get started. This utility will gather the required config for your deployment. Run the following command from your terminal:

npx cobrowse-enterprise create aws ./example

You can replace "./example" with the directory where you wish to save the configuration data. The directory will be created if it does not exist yet.

4. Deploy the Terraform

Once you have successfully generated a configuration directory via our command line utility you are then ready to deploy the terraform to AWS.

Navigate to the configuration directory you created and run the following commands:

terraform init

This will instruct terraform to prepare the resources it needs to deploy.

Note: During the first attempt of the following deployment an SSL certificate will be generated by Amazon Certificate Manager. During deployment you will need to head to ACM and approve the certificate request by performing the manual steps required by AWS. This is an Amazon process that requires adding a DNS record to validate domain ownership. You should only need to complete this approval once for your Cobrowse domain.

Run the following command to start the deployment of resources to AWS:

terraform apply

This will list the modifications that terraform will make to your AWS account. If that looks good, type 'yes' to continue the deployment.

If the output of terraform shows that the ingress endpoint was not created as in the example below, please verify the state of the generated certificate in ACM. Make sure that the certificate is issued or proceed with the validation.

Apply complete! Resources: 144 added, 0 changed, 0 destroyed.

Outputs:

dns_name = "Ingress endpoint not created. Please check Amazon Certificate Manager."
domain = "example.com"

It can take up to 30 minutes until the ingress is created. Run the following command to get an updated status:

terraform refresh

You should have an output as described in Section 5.

Configure kubectl

kubectl is a utility for managing the Kubernetes clusters. If you have not configured kubectl to talk to your new EKS cluster, you can do so using the AWS CLI:

aws eks update-kubeconfig --name cobrowse-enterprise

When configured, test that it works by running:

kubectl get pod

5. Configure your DNS provider

Once the terraform managed resources have been deployed to AWS, you should have an output similar to this:

Apply complete! Resources: 144 added, 0 changed, 0 destroyed.

Outputs:

dns_name = "k8s-default-apiingre-38e727b290-XXXXXXXXXX.eu-west-1.elb.amazonaws.com"
domain = "example.com"

The last step is to configure the required DNS record with your DNS provider (e.g. Route 53). We will not do this automatically.

Create a CNAME to direct the domain to the dns_name value shown in the output from terraform apply.

6. Check your deployment

Your deployment should now be available. Open up a web browser to your Cobrowse domain and check the deployment!

Running your instance

Monitoring your Deployment

Here we've listed a few useful resources created by our Terraform. These can be used to check on the health of your deployment, or dig into any errors you might be experiencing:

View your cluster in EKS. There should be several Kubernetes Deployments and StatefulSets running. Each should have at least one stably running pod.

CloudWatch Logs for application level logging. Note: we recommend using a command line tool like awslogs to make viewing the aggregated log stream easier. Standard kubectl logs commands will also work to view application logging.

Our Kubernetes deployment also support Prometheus application metrics, however this is not configured automatically. See our docs on configuring the Prometheus integration for CloudWatch.

Managing your deployment

Next, learn about managing and upgrading your deployment.

Managing your deployment