Configuring Confluence Data Center to work with Amazon Aurora

On this page:

Confluence Data Center supports the use of a single-writer, PostgreSQL-compatible Amazon Aurora clustered database. A typical production-grade cluster includes one or more readers in a different availability zone. If the writer fails, Amazon Aurora will automatically promote one of the readers to take its place. For more information, see Amazon Aurora Features: PostgreSQL-Compatible Edition.

Deploying Confluence Data Center with Amazon Aurora

The AWS Quick Start template as a method of deployment is no longer supported by Atlassian. You can still use the template, but we won't maintain or update it.

We recommend deploying your Data Center products on a Kubernetes cluster using our Helm charts for a more efficient and robust infrastructure and operational setup. Learn more about deploying on Kubernetes.

AWS now recommends switching launch configurations, which our AWS Quick Start template uses, to launch templates. We won’t do this switch, however, as we’ve ended our support for the AWS Quick Start template. This means you're no longer able to create launch configurations using this template.

To create a new Confluence Data Center deployment with Amazon Aurora, you can still use the AWS Quick Start for Confluence, though AWS Quick Start templates are no longer supported or maintained by Atlassian. This Quick Start lets you configure a PostgreSQL-compatible Amazon Aurora cluster with one writer and two readers in separate availability zones. See Running Confluence Data Center in AWS for more information. 

Connecting an existing Quick Start deployment to Amazon Aurora  

If you deployed Confluence Data Center using the Quick Start before 11 June 2019, you won’t be able to connect it to a new Amazon Aurora cluster. The Quick Start version prior to that date applied some settings that are incompatible with Aurora.

Instead, you’ll have to migrate your existing data to a new Confluence Data Center deployment:

  1. Use the latest AWS Quick Start for Confluence to create a new Confluence Data Center deployment.

  2. Shut down Confluence on the application nodes of both old and new deployments. If you use a standalone Synchrony cluster, shut down all the nodes in that cluster too.

  3. Migrate your data from the old deployment to the new one:

    • EFS: EFS-to-EFS Backup explains how you can use an easy-to-deploy backup solution to perform a backup of your old EFS and restore it in the new deployment. 

    • Database: Migrating Data to Amazon Aurora PostgreSQL contains instructions for migrating from Amazon RDS to a PostgreSQL-compatible Amazon Aurora cluster.

Once you finish the migration, re-start Confluence on all application nodes in the new deployment. If you use a standalone Synchrony cluster, re-start all its nodes. 

We strongly recommend you rebuild your content index after performing a migration, to ensure Confluence search works as expected.  

Manually setting up an Amazon Aurora Database

Confluence Data Center specifically supports the use of an Amazon Aurora cluster with the following configuration:

  • It must have only one writer, replicating to one or more readers.

  • Your PostgreSQL engine must be version 9.6 or higher.

Check Supported Platforms for more details.

AWS documentation

AWS has some helpful guides for setting up an Aurora database and migrating to it:

Amazon also offers an AWS Database Migration Service to facilitate a managed migration. This service offers minimal downtime, and supports migrations to Aurora from a wide variety of source databases.

If you deployed Confluence Data Center through our AWS Quick Start before 11 June 2019, you can’t connect it to a new Amazon Aurora cluster. Rather, you’ll need to re-deploy Confluence Data Center using our updated Quick Start and migrate your data across. See Connecting an existing Quick Start deployment to Amazon Aurora for more information.


Connecting Confluence Data Center to a new Amazon Aurora database

After deploying an Aurora cluster and migrating your database to it, you’ll need to properly connect it to Confluence. This will involve updating the database URL used by Confluence Data Center.

Confluence Data Center should point to the the Aurora cluster writer endpoint URL, and include the targetServerType parameter. This parameter allows Confluence to target the writer database instance, which ensures the application can reconnect to it after a failover.

Your database URL will look something like this:

jdbc:postgresql://<CLUSTER_WRITER_ENDPOINT>:<CLUSTER_WRITER_PORT>/<DATABASE_NAME>?targetServerType=master

If you deployed your Aurora cluster through the Modular Architecture for Amazon Aurora PostgreSQL Quick Start, you can find then the cluster writer details from the Outputs tab in AWS. The RDSEndpointAddress and RDSEndpointAddressPort values will be your CLUSTER_WRITER_ENDPOINT and CLUSTER_WRITER_PORT , respectively.

The following steps will walk you through the process of connecting Confluence and Aurora.

Step 1: Shut down Confluence Data Center

To safely reconfigure Confluence Data Center’s database connection, we recommend a full outage. To do this, stop Confluence on all application nodes.

If you have a standalone Synchrony cluster, stop Synchrony on each node there.

Step 2: Update the database URL each Confluence node uses

How you perform this step depends on how Confluence currently connects to your database.

If you use a direct JDBC connection

  1. On the first node, edit the <local-home>/confluence-cfg.xml file.

  2. Update the hibernate.connection.url property with your cluster writer endpoint URL as follows:

    <property name="hibernate.connection.url">jdbc:postgresql://<CLUSTER_WRITER_ENDPOINT>:<CLUSTER_WRITER_PORT>/<DATABASE_NAME>?targetServerType=master
  3. Repeat this change on all other nodes.

  4. Start Confluence, one node at a time.

This change must be made in the local home directory on each node, not in the copy of the confluence-cfg.xml that can be found in the shared home.

If you use a datasource connection

  1. Stop Confluence on all nodes.

  2. On the first node, edit the <install-directory>/conf/server.xml file.

  3. Update the url parameter in the datasource Resource element with your cluster writer endpoint URL as follows:

    <Resource name="jdbc/confluence" auth="Container" type="javax.sql.DataSource" 
    username="<database-user>" 
    password="<password>" 
    driverClassName="org.postgresql.Driver" 
    url="jdbc:postgresql://<CLUSTER_WRITER_ENDPOINT>:<CLUSTER_WRITER_PORT>/<DATABASE_NAME>?targetServerType=master" 
    maxTotal="60" 
    maxIdle="20" 
    validationQuery="select 1"/>
  4. Repeat this change on all other nodes.

  5. Start Confluence, one node at a time.

Step 3: Configure collaborative editing

Synchrony, the engine that powers collaborative editing, can be deployed in two different ways, which affects how you pass the database URL:

  1. Managed by Confluence - Confluence will automatically launch a Synchrony process on the same node, and manage it for you.

  2. Standalone Synchrony cluster - You deploy and manage Synchrony standalone in its own cluster with as many nodes as you need. This is the default method when you deploy Confluence in AWS using our Quick Start.

If Synchrony is managed by Confluence, you don't need to do anything. Confluence will pass the URL to Synchrony for you.

If you run a Standalone Synchrony cluster, you will need to provide the cluster writer endpoint URL in your startup script. This script will be either <synchrony-home>/start-synchrony.sh or start-synchrony.bat, depending on your operating system. Edit your script as follows:

start-synchrony.sh (Linux)
DATABASE_URL="jdbc:postgresql://<CLUSTER_WRITER_ENDPOINT>:<CLUSTER_WRITER_PORT>/<DATABASE_NAME>?targetServerType=master"
start-synchrony.bat (Windows)
set DATABASE_URL=jdbc:postgresql://<CLUSTER_WRITER_ENDPOINT>:<CLUSTER_WRITER_PORT>/<DATABASE_NAME>?targetServerType=master

See Set up a Synchrony cluster for Confluence Data Center for more information about setting up Synchrony standalone cluster.

If you run Synchrony as a Linux service, you'll need to reinstall the service.


Step 4: Restart Confluence

After making the necessary database URL updates, you can now restart Confluence on each application node, one node at a time.

If you have a standalone Synchrony cluster, restart it on each of the cluster’s nodes.

Last modified on Sep 10, 2024

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.