How to use the Data Center Migration app to migrate Jira to an AWS cluster
Solution
The Jira Data Center Migration app automates many of the steps involved in:
- deploying new, cluster-ready infrastructure, and
migrating all the data from your existing instance to it.
The app uses CloudFormation templates to help you deploy a fully supported, cluster-ready Jira Data Center on AWS. This deployment will have a load balancer and one Jira Data Center node. You can scale this up after finishing the migration.
After deploying Jira Data Center on AWS, the app will migrate your projects, issues, attachments, and other data across. This migration is fairly self-contained, meaning it won’t affect your existing instance’s data. As such, you can review and test the new deployment with your migrated data; from there, you can decide whether or not you want to start using new deployment. This lets you safely test the app's deployment and data transfer multiple times without risking data loss or corruption.
Can I use the Jira Data Center Migration app?
Yes, but only if your Jira Software instance is:
version 7.13.0 and above
using a PostgreSQL database
running on a Linux server
using a Jira Data Center license
We will expand compatibility as demand grows.
What data does the app migrate?
The Jira Data Center Migration App will migrate your:
- Jira application home directory, and
- Jira database
How does the Jira Data Center Migration app handle the migration of other apps?
Most apps from the Atlassian Marketplace store their data in Jira's home directory and database. If an app (or its data) is stored on a different directory or in a database separate from Jira's, it won't get migrated. If this occurs, you'll have to reinstall it on your new Jira instance and migrate its data manually.
Data Center app licenses
If you're migrating from a Jira Server instance, check if your apps have a Data Center Approved version. If they do, you'll have to upgrade their license as well when you migrate. See Data Center Approved Apps for more information.
What are the app's AWS requirements?
You’ll also need an AWS account. Your account should have permissions and funds to provision resources on AWS, including Amazon S3, EC2, and EFS. The app will use your AWS account to deploy all the required infrastructure.
How will the migration impact users?
The Jira Data Center Migration app will run part of the migration process without downtime. However, during this time the process can impact your instance’s performance. As such, we recommend that you start running it during periods of low usage. For example, you can start the migration process on Friday night, when you expect the least amount of users.
After the app copies your content, you’ll have to block user access to it. This is to help ensure a safe database sync. Consult your team on an appropriate time to do this.
What will my new deployment look like?
The Jira Data Center Migration app deploys a cluster-ready Jira Data Center instance on AWS. It features the following architecture:
This deployment consists of the following components:
Instances/nodes: One or more Amazon Elastic Cloud (EC2) instances as cluster nodes, running Jira.
Load balancer: An Application Load Balancer (ALB), which works both as load balancer and SSL-terminating reverse proxy.
Amazon EFS: A shared file system for storing artifacts in a common location, accessible to multiple Jira nodes. The Quick Start architecture implements the shared file system using the highly available Amazon Elastic File System (Amazon EFS) service.
An Atlassian Standard Infrastructure (ASI) stack, which will provide all your necessary networking components.
Click here for more information about the ASIThe ASI is a highly available, secure virtual private cloud (VPC) specifically customized to host Atlassian Data Center products on AWS. The ASI contains basic networking components required by Jira Data Center, and makes it easier to integrate multiple Atlassian Data Center products under a shared infrastructure. The following diagram shows the different components set up by the ASI:
A fully configured PostgreSQL database (with optional high availability)
(Optional) Amazon CloudWatch, to help you monitor your deployment
(Optional) Bastion host: This host enables secure SSH access to Jira Data Center without exposing it to the internet. For more information, see Bastion Hosts.
You can deploy without a Bastion host if you prefer to access Jira Data Center through the AWS Systems Manager Sessions Manager.
For more information, see Jira products on AWS.
Step 1: Plan your migration
The Jira Data Center Migration app helps minimize the amount of planning and research required to migrate to a clustered deployment. With the app, you can focus on the following aspects of your migration:
External integrations
The app isn't designed to migrate any external integrations. If your existing Jira instance integrated with any services or applications, you’ll likely need to set them up again after migration. Examples of such integrations are SalesForce, GitHub, Splunk, and SAML.
Before you start the migration, create a checklist of all the integrations you may need to set up again. Keep in mind that you’ll need to:
Reconnect any external integrations (if you have any). These include apps that communicate directly with your Jira Server’s API and third-party monitoring platforms. Re-familiarize yourself with the procedures for integrating these services, as you’ll need to do this again on your new deployment.
Reconnect your external user directory (if you use one). Review Configuring user directories for instructions.
If you use SAML SSO, you may also need to set this up again.Re-install some apps – in particular, custom apps and other apps that don't store their data on Jira's database or application home directory. If your apps have a Data Center version, make sure you use those on your new deployment. See About Data Center approved apps for more information.
Migration schedule
The Jira Data Center Migration app performs a full, guided migration in 3 phases:
| Deployment | Data copy | Final sync |
|---|---|---|
The app will deploy your Data Center infrastructure, using best-practice defaults for any setting you don’t configure. This process can take up to an hour. It won't require downtime or affect Jira's performance | The app will copy your home directory contents. This phase won't require downtime, but it could affect your existing instance's performance. It can take awhile depending on the size of your home directory. | After copying your home directory, the app will need to sync your database. To do this, you'll have to block users from accessing your old Jira instance. |
The Data copy and Final sync phases will impact the work of your end-users. Consult them (or their representatives) to work out an agreeable timeline for the migration.
Use your downtime wisely
The Sync phase’s downtime will give you an opportunity to re-configure all the integrations and apps you listed earlier. Make sure you account for the time it’ll take to work through this checklist during downtime.
Prepare a downtime page
While user access is blocked during the Sync phase, you'll need a temporary page for users. Prepare one beforehand; you'll need to redirect your Jira domain to that page during downtime.
Step 2: Set up the requirements
The Jira Data Center Migration app simplifies your AWS infrastructure’s deployment by choosing the right settings for most components. The following sub-sections will guide you through some preparations you need to make before kicking off the migration.
Set up your AWS credentials
The app will require your AWS login credentials in order to deploy infrastructure on it:
AWS access key ID
AWS secret access key
Prepare these credentials before you start your migration. For instructions on how to do this, see Access Keys.
Required IAM role permissions
If your organization is providing you an IAM role to access AWS, make sure it has the right permissions. The following JSON policy file contains all the permissions needed by the app:
See Importing Existing Managed Policies for instructions on how to import both policies into your IAM role.
Upgrade your license to Data Center
The Jira Data Center Migration app deploys clustered infrastructure. This is only supported on Jira Data Center – that means you need to get a Data Center license. For more information, see Data Center Licensing and Pricing.
Replace your current instance's license with your new Jira Data Center license. The app will migrate your license details along with the rest of your data. For instructions on how to update your license, see Licensing your Jira applications.
Use a trial license for evaluation
You can also use a trial license with the app. To generate a trial license, log in to your Atlassian account and click New Trial License.
Migrating without a Data Center license
You can still use the Jira Data Center Migration app while still using a Jira Server license. However, you'll still need to upgrade to a Data Center license in order to continue using Jira after migrating.
Import certificate for HTTPS
For added security, we strongly recommend that you enable HTTPS on your new deployment. The app simplifies this process by just asking you for a valid certificate. This certificate must be imported to the AWS Certificate Manager.
Use the AWS Certificate Manager to get your certificate's Amazon Resource Name (ARN). You'll use the ARN later when you configure your AWS deployment.
Install PostgreSQL client
The app uses the pg_dump utility to back up your database. This means you’ll need to install the PostgreSQL client on your Jira host.
Each operating system has different methods for installing this client. Refer to the PostgreSQL Downloads page for the right instructions for your operating system.
Migrating from a cluster
If you are migrating from Jira Data Center cluster, you'll need to install pg_dump on all the nodes in that cluster.
If your backup host uses Amazon Linux, run the following command:
amazon-linux-extras install -y postgresql9.6(Optional) Create a key pair
You’ll need to be able to access your infrastructure on AWS after deployment. If you prefer to do this through a Bastion host, you’ll need to create a Amazon EC2 Key Pair. This key pair will provide you with the credentials you’ll need to access your nodes via SSH later on. For more information, see Creating a Key Pair Using Amazon EC2.
You can skip this step if you don't plan to deploy a Bastion host.
(Optional) Create a local Jira System Administrator account
If your admin account is managed or authenticated externally, you might not be able to use it on the migrated Jira instance. You'll need to manually re-connect any external user directories or SSO on your newly migrated Jira instance. However, until you do, any user accounts that depend on either one won't be able to log in.
To ensure you'll be able to log in to your migrated Jira instance, create a new user account on Jira's internal user directory. Then, assign the Jira System Administrator global permission to the account.
Step 3: Kicking off the migration
You can install the Jira Data Center Migration app directly through the Universal Plugin Manager. For detailed instructions, refer to the app's installation instructions.
Once installed, go to 
> System. Select Data Center Migration to open the Jira Data Center Migration app:
Select Start migration. The app will then guide you through the entire deployment and migration process.
Customizing your deployment
The app will deploy Jira Data Center using the same version as your current instance. This helps avoid any risks that could result in inconsistencies or data loss. You can always upgrade later on after you've completed the migration process.
The defaults used by the app are suitable for most deployments. You can also change most of them later on after deployment. However, you’ll need to set the following parameters correctly before deployment, as you won’t be able to easily change them later:
| Database | |
|---|---|
Parameter label (name) | Description |
Master (admin) password | The password for the master ( |
Enable RDS Multi-AZ deployment | This parameter sets whether to enable high availability for your chosen database engine. |
Application user database password | The password for the database user account. Must be at least 8 characters and include 1 uppercase, 1 lowercase, 1 number, and 1 of the following symbols: |
| Networking | |
Parameter label (name) | Description |
SSL certificate ARN ( | Enter the Amazon Resource Name (ARN) of the certificate you imported earlier. This will enable SSL, using your certificate to secure connections. |
Availability Zones ( | The list of Availability Zones to use for the subnets in the ASI. The Quick Start uses two Availability Zones from your list and preserves the logical order you specify. |
Permitted IP range ( | Enter the CIDR IP range that should be permitted access Atlassian services. We recommend that you set this value to a trusted IP range. For example, you might want to grant only your corporate network access to the software. |
Key name ( | Enter the key pair you created earlier. This public/private key pair will allow you to connect to your deployment via SSH later on. |
Deploying with one node
The following parameters control the number of Jira application nodes on your cluster:
Maximum number of cluster nodes (
ClusterNodeMax)Minimum number of cluster nodes (
ClusterNodeMin)
When you deploy for the first time, set both parameters to 1. You can scale up your cluster later on after you finish migrating your data.
Blocking user access to your old Jira instance
Once the app enters the Sync phase, it'll prompt you to block user access to your Jira instance. You need to do this to reduce any risk of data corruption during database sync.
To do this, set your DNS to redirect your Jira domain elsewhere. If you set a temporary downtime page, use that.
Step 4: Setting up and testing your new deployment
Once the finishes migrating your content, you can start setting up your new deployment.
Perform a full Jira re-index
The migration process can result in discrepancies in Jira's index. To address this, you'll need to manually rebuild Jira's search index. You'll need to do perform a Full re-index.
See:
- Search indexing (for step-by-step instructions on performing a re-index)
- Re-indexing after major configuration changes
Re-integrate all external services
Re-connect all external services your old instance used; start by going through the checklist you created earlier. For example, if your old instance used an external user directory, re-authorize your new Data Center deployment to use it.
Test your new AWS deployment
Your new Jira Data Center will be accessible via a new URL, which the app will provide. Use this URL to start testing the new deployment. Validate that:
all your data has been successfully migrated, and
all your external dependencies (if any) are integrated.
Redirect your DNS
Once you're satisfied with the state of your new deployment, configure your DNS to point to its URL. Your users should then be able to reach your new Jira Data Center deployment via the same domain they used before.
Additional resources
For more information about running and managing the Jira Data Center cluster deployed by the app, check out these resources:
If your team prefers less frequent version upgrade, we recommend that you upgrade to a Long Term Support release.
Troubleshooting
The following subsections show how to address common issues on your new Jira Data Center deployment on AWS.
Manually terminating all provisioned AWS resources
If the migration process fails or is cancelled for any reason, you may need to start over. When this happens, you might also need to manually terminate all stacks (including nested ones) and secrets already provisioned by the app. The names of the stacks and secrets you need to delete will contain the Stack name you entered earlier during configuration.
For more information on how to delete these resources, see:
Log in to the application node
You can perform node-level configuration or maintenance tasks on your deployment through the AWS Systems Manager Sessions Manager. This browser-based terminal lets you access your nodes without any SSH Keys or a Bastion host. For more information, see Getting started with Session Manager.
Access via Bastion host
You can also access your nodes via a Bastion host (if you deployed one). To do this, you'll need your SSH private key file (the PEM file you specified for the Key Name parameter). Remember, this key can access all nodes in your deployment, so keep this key in a safe place.
The Bastion host acts as your "jump box" to any instance in your deployment's internal subnets. That is, access the Bastion host first, and from there access any instance in your deployment.
The Bastion host's public IP is the BastionPubIp output of your deployment's ATL-BastionStack stack. This stack is nested in your deployment's Atlassian Standard Infrastructure (ASI). To access the Bastion host, use ec2-user as the user name, for example:
ssh -i keyfile.pem ec2-user@<BastionPubIp>
The ec2-user has sudo access. SSH access is by root is not allowed.
Restart Jira on the application node
If you're experiencing unexpected issues with your new Jira deployment, try restarting Jira on the application node first.
The app will install Jira on the application node as a Systemctl service. This means you need to use the systemd utility to stop, start, or restart Jira. For example, to restart Jira, log in to the application node and run:
sudo systemctl restart jira
Create a temporary admin account
If you're having trouble logging in to Jira, you can create a temporary admin account through Jira's recovery mode. This mode will let you create a temporary admin account which you can use to log in and troubleshoot further. See Restore Passwords To Recover Admin User Rights in Jira Server and Data Center.
To go into Jira's recovery mode, you'll need to access the application node on AWS through SSH.
Bypass SAML
If your original Jira instance used SAML SSO, you'll need to manually set it up again on your newly migrated instance. However, you might not be able to log in because the instance can't authenticate you yet.
You can work around this by bypassing SAML when you log in on your new Jira instance. See Bypass SAML authentication for Jira Data Center.
Remove offline or abandoned nodes
If you migrated from another Jira Data Center cluster, your new Jira instance might detect many offline nodes. This is usually because Jira is still attempting to contact nodes from your old deployment. This can affect your deployment's performance and generate an unusually large number of logs.
To address this, you'll need to manually remove the offline nodes from Jira's registry. See Remove abandoned or offline nodes in Jira Data Center.