How to use the Data Center Migration app to migrate Jira to an AWS cluster

Still need help?

The Atlassian Community is here for you.

Ask the community

Platform Notice: Server and Data Center Only - This article only applies to Atlassian products on the server and data center platforms.

Purpose

Migrating a large organization's old, bare-metal Jira Server to a Jira Data Center cluster often involves careful planning, as described in our Atlassian Data Center migration plan

For smaller organizations, you can use the Jira Data Center Migration app to streamline the migration process. This app walks you through a largely automated journey through deployment and migration, with minimal planning.


On this page

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:

We will expand compatibility as demand grows. 

What data does the app migrate?

The Jira Data Center Migration App will migrate your:

Here's a list of what's migrated

Jira Software project data

  • Issue rank

  • Epics (epic link)

    • Epic name

    • Epic color

    • Epic link

    • Epic status

  • Issue history (including all custom fields)

    • Epic Name

    • Epic Color

    • Epic Link

    • Epic Status

    • Issue rank

    • Original Estimate

    • Remaining Estimate

    • Flagged

    • Components

    • Environment

  • Sprints

  • Versions (affects versions, Fix versions)

  • Filters associated with boards being migrated

  • Boards connected to only one project that is being migrated

Jira Core project data

  • Project details:

    • Name

    • Key

    • Project type

    • Project category

    • Description

    • Project lead

    • Default assignee

  • Project roles

  • Issue types

  • Issue type scheme

  • Issue type screen scheme

  • Workflows scheme

  • Field configuration scheme

  • Workflows - basic links to the correctly migrated workflow scheme with status and transitions

  • Workflow functions

    • Validator: permission,

    • Condition: permission, allow only reporter

    • Post Function: update resolution field, assign to current user, assign to reporter, assign to lead

  • Screens schemes

  • Screens

  • Status category

  • Permission schemes

  • Issue security

Issue data

  • Summary

  • description

  • Issue type

  • Status

  • Priority

  • Resolution

  • Labels

  • Reporter

  • Assignee

  • Due date

  • Subtasks

  • Some custom fields

    • Text

    • Date

    • Number

    • Time

    • Labels

    • Select List (single choice)

    • Checkbox

    • User Picker (single/multiple)

    • Group custom fields

    • Multi-line text

    • Radio button

    • Environment

  • @mentions

  • Watchers/ Votes

  • Issue links (including link types)

  • Attachments

  • Comments

  • Comments with security

  • Story points

  • Time spent

  • Issue history

  • Issue work log

Jira Software Boards

  • Boards

    • Name

    • Administrators

    • Filter & permissions

    • Location

  • Advanced board settings

    • Column names & status mapping

    • Quick filters

    • Swimlanes

    • Sprint permissions

    • Card colors

    • Time statistic / estimation

Project setup

  • Other Custom Fields

    • Single and Multi-version picker

    • URL

    • Select List (cascading)
    • Select List (multiple choice)

    • Project picker
  • Custom field language translations

  • Workflow functions

    • Validator: required field, field changed

    • Condition: user in group, in project role, field value, subtask blocking

    • Post Function: clear field value, update custom field, copy value from other field, delegating

  • Project avatars

  • Links to issues or entities that are not migrated

Other project types

  • Jira Service Desk projects
  • Archived projects - to migrate archived projects, reactivate them before migrating.

Jira global entities and permissions

  • Global permissions

  • General configuration (timezone, language, etc)

  • Dashboards

  • Cross-project boards

  • Boards not connected to the projects being migrated

  • Filters on boards that are not migrated

  • Confluence links

Users and groups

License information

Here's a list of what isn't migrated

External integrations

If your Jira instance is integrated with any third-party services (including SAML SSO and external user directories like LDAP or Active Directory), you may need to reconnect them after migration.

Search index

Jira's search index will likely become out-of-sync during the migration. If this happens, you'll have to manually rebuild it

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 S3EC2, 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 ASI

    The 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)

    Click here for more information about the database

    The app uses Amazon RDS for PostgreSQLas a primary database instance, replicating to a standby instance hosted in a different AZ. Should the primary database instance fail, Amazon RDS will perform an automatic failover to the replica. For related information about high availability with Amazon RDS, see Multi-AZ Deployments.

  • (Optional) Amazon CloudWatch, to help you monitor your deployment

    Click here for more information about Amazon CloudWatch

    The Quick Start can also provide you with node monitoring through Amazon CloudWatch. This will allow you to track each node's CPU, disk, and network activity, all from a pre-configured CloudWatch dashboard. The dashboard will be configured to display the latest log output, and you can customize the dashboard later on with additional monitoring and metrics.

    By default, Amazon CloudWatch will also collect and store logs from each node into a single, central source. This centralized logging allows you to search and analyze your deployment's log data more easily and effectively. See Analyzing Log Data with CloudWatch Logs Insights and Search Log Data Using Filter Patterns for more information.

    Amazon CloudWatch provides basic logging and monitoring, but also costs extra. To help reduce the cost of your deployment, you can disable logging or turn off Amazon CloudWatch integration during deployment.

    tip/resting Created with Sketch.

    To download your log data (for example, to archive it or analyze it outside of AWS), you’ll have to export it first to S3. From there, you can download it. See Exporting Log Data to Amazon S3 for details.

  • (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:

  1. 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.

  2. 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.

  3. 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:

DeploymentData copyFinal 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.

tip/resting Created with Sketch.

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:

DCMA-policy.json

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.

tip/resting Created with Sketch.

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.

You have two options for obtaining and importing a certificate.

Option 1: You can request a certificate directly from AWS. When you do, it'll be imported directly into AWS Certificate Manager. Refer to the following resources for instructions:

Option 2: Alternatively, you can obtain a valid certificate issued by a trusted Certificate Authority. Once you have a certificate, you'll need to import it into 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 
(DBMasterUserPassword)

The password for the master (postgres) account. Must be at least 8 characters and include 1 uppercase, 1 lowercase, 1 number, and 1 of the following symbols: ! # $ { * : [ = , ] - _ @ + % &

Enable RDS Multi-AZ deployment
(DBMultiAZ)

This parameter sets whether to enable high availability for your chosen database engine.

Application user database password 
(DBPassword)

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 (SSLCertificateARN)

Enter the Amazon Resource Name (ARN) of the certificate you imported earlier. This will enable SSL, using your certificate to secure connections.

Availability Zones (AvailabilityZones)

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 (CidrBlock)

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 (KeyPairName)

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:

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. 

A Long Term Support release is a feature release that gets backported critical security updates and critical bug fixes during its entire two-year support window. If you can only upgrade once a year, consider upgrading to a Long Term Support release. Learn more

Long Term Support releases were originally referred to as Enterprise Releases.

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.

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.





robotsnoindex


Last modified on Aug 13, 2020

Was this helpful?

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