This page describes the implementation of data residency features in Connect apps. For information about data residency in Forge apps, refer to the Forge documentation.
For more details on data residency works for admins (including a glossary of terms) see Manage data residency.
Atlassian data residency enables Atlassian organization administrators to specify where subsets of their product data at rest are hosted. Each realm contains geographical regions. Administrators can choose between the following realms:
To support all the data residency use cases, apps have to implement both the realm pinning and the real migration capabilities.
Here is how the capabilities are used:
regionBaseUrls control the location when an app is initially installed. After a customer moved a product to a specific location, when an app is installed, the corresponding location from the Connect descriptor will be selected. Even if the product has not been moved to a specific location, the regionBaseUrls is used at app installation time if the app supports the location where the product is provisioned.dare-migration hook is used when a customer requests a migration for the app data because the app is not in the same location as the product. This might be the case when the app was installed in a global location because the app didn’t have a regionBaseUrls section defined in its descriptor, or didn’t support the region where the host product was provisioned. Even if the app supported the regionBaseUrls at installation time, customers might have subsequently moved the product to a different location to comply with their data residency requirements. In these cases, customers will request the app data to be moved via the customer-facing UI.Adopting data residency is not compulsory, you can choose to maintain your app as-is. However, if you choose not to support regional data storage customers with stringent realm requirements may not be able to install your app.
To enable an app to use data residency:
regionBaseUrls field to the app descriptor.The regionBaseUrls field follows the same standards as the app’s main baseUrl field. The supported region keys are “EU”, “US”, "AU", "DE", "SG", "CA", "IN", "KR", "JP", "GB" and "CH".
The URLs listed in the following example are the address of the app within the given realm, and the app will store all data at rest within that realm.
1 2{ ... "regionBaseUrls": { "US": "https://us.your.sample.app.com", "EU": "https://eu.your.sample.app.com", "AU": "https://au.your.sample.app.com", "DE": "https://de.your.sample.app.com", "SG": "https://sg.your.sample.app.com", "CA": "https://ca.your.sample.app.com", "IN": "https://in.your.sample.app.com", "KR": "https://kr.your.sample.app.com", "JP": "https://jp.your.sample.app.com", "GB": "https://gb.your.sample.app.com", "CH": "https://ch.your.sample.app.com" } }
Customers who chose a single realm require an app to list that realm in its list of supported realms. For example, a customer who chooses US data residency requires a URL that specifies the US:
1 2"regionBaseUrls": { "US": "https://us.your.sample.app.com" }
or a list of URLs that include the US:
1 2"regionBaseUrls": { "US": "https://us.your.sample.app.com", "EU": "https://eu.your.sample.app.com" }
Customers who don’t have a data residency requirement, but are provisioned in a supported region for performance reasons, install into the nearest supported realm - otherwise into the global realm. This may provide performance improvements for end users.
To support data resident customers, you may need to spin up stacks outside of your current infrastructure then create databases for each realm, depending on how your app is structured.
You will need to provide a data residency policy, similar to the Atlassian Data Residency policy, and update any of your other customer policies affected.
If you indicate support for a realm, it doesn't mean your app simply supports customers in that realm. It means your app only stores the relevant, in-scope data in that realm and any in-scope data that you store must be stored in that realm.
To support data residency migrations, you must support the data residency migration hook specified in the lifecycle field in the descriptor and the subsequent hooks part of the lifecycle of a migration.
A new lifecycle can be specified as follows:
1 2{ ... "lifecycle": { "installed": "/installed", "dare-migration": "/my-cool-migration-hook" }, ... }
This makes your app eligible to receive the following compulsory hooks:
/schedule/start/status/commit/rollbackWe will append this hook onto your declared dare-migration lifecycle in the descriptor, for example: /my-cool-migration-hook/schedule.
These new lifecycles don't come from the product. Instead, they come from a new service. This is to facilitate the migration process while the product is down.
The service will continue to communicate with apps by signing the JWT token with the sharedSecret.
You should continue to verify the request as described
on Understanding JWT for Connect apps.
| Endpoint | Description | Request payload | Response |
|---|---|---|---|
POST /schedule | When a product admin schedules a migration, the service will notify eligible apps via this endpoint to schedule a migration. Use this to do any preparatory work prior to the migration. |
| If your app returns a non-2xx response without an errorResponseCode, we will retry up to two times. If these attempts are unsuccessful, the app migration is marked as a failure, and a rollback hook will be dispatched. |
POST /start | Once the site is taken offline, the service will notify eligible apps that have successfully responded to the schedule hook via this endpoint to begin the migration. |
| If your app returns a non-2xx response without an errorResponseCode, we will retry up to two times. If these attempts are unsuccessful, the app migration is marked as a failure, and a rollback hook will be dispatched. |
GET /status | This endpoint will be called by the service to fetch the status of an ongoing migration. The statuses the service will specifically be looking for are:
failed, there will be a series of errorResponseCodes you may wish to report back with to provide more insight into the failure reason. This is described further under the Error Codes heading.
A Beyond that, you can use any statuses you wish. However, upon completion, any status that isn't Once the migration starts, we'll also be regularly polling the apps for their status. If all apps have either | {} | Failed status - service will update the app migration’s status to failed:
App is awaiting a /commit hook. The service, once the migration ends, will send a /commit hook:
|
POST /commit | Once the site is brought back online, the service will query the status of each app that has started the migration.
The service will ask apps to commit via this endpoint if they’ve reported that they're Specifically, this is to commit the copied data to the new region. | {} | If your app returns a non-2xx response without an errorResponseCode, we will retry up to two times. If these attempts are unsuccessful, the app migration is marked as a failure, and a rollback hook will be dispatched. |
POST /rollback | There are various use cases for this endpoint:
ready-to-commit by the app.
Once the site is brought back online, the service will query the status of each app which has started the migration.
The service will ask apps to roll back via this endpoint if they’ve reported that they aren't Specifically, this is intended to roll back the non-destructive copy operation to the new region. | {} | Not applicable. |
The migration hooks use a retry mechanism to handle transient errors and increase the chances of a successful migration. The hooks are retried up to 2 times after the initial call. The exemption is the status hook which is dispatched every 5 minutes.
A retry is triggered when the app responds with a non-2xx code and no errorResponseCode. If an errorResponseCode is received, it signals a failure, stopping further retries.
There is a 5 second pause between retries.
To help diagnose problems with migrations, we’re adding a set of standardised error codes that your app can report back to us with when you’re reporting back with a non-2xx to the hooks or the status retrieval.
Any non-2xx response to any of the lifecycle events can optionally include any of the below error codes in its response to assist the user in understanding why the migration may have failed.
1 2{ “errorResponseCode”: “E0004” }
| Error Code | Reason |
|---|---|
E0001 | The migration was not scheduled. |
E0002 | The app does not support the target region (versioning issues). |
E0003 | The app does not support migrations (versioning issues). |
E0004 | The app has too many concurrent migrations. |
E9999 | Generic failure code. |
There are a few considerations you should think about when deciding to implement data residency migrations for Connect apps.
/schedule endpoint./schedule endpoint to begin the migration via the /start endpoint./status.
ready-to-commit, our service will send a /commit hook./rollback hook.failed or ready-to-commit when polled or reported back early):
ready-to-commit, our service will send a /commit hook./rollback hook.Planning a migration downtime is challenging for enterprise customers, therefore a shorter app migration window encourages customers to migrate their apps. The app descriptor supports a maxMigrationDurationHours property, allowing partners to specify the maximum migration window. If this property is not declared, the maximum migration window will default to 2 hours.
240.50.5 only. i.e. 1, 1.5, 2 (0.7 for example would be invalid)1 2{ ... "dataResidency": { "maxMigrationDurationHours": 0.5, ... }
If an app fails to migrate within the specified maxMigrationDuration window, the /rollback hook will be sent.
A manual alternative to perform a test migration without using the UI is also available. This options allows for more control over an app data residency migration flow.
You can manually test migrations by raising a support request.
The requirements for a manual migration are:
The manual migration testing process differs from the actual migration flow in the following ways:
To perform a manual migration test:
addonKey specified in your descriptor.This process is intended for testing purposes only and should NOT be utilised to perform migrations on your customer sites.
All apps supporting data residency migration via the dare-migration hook will receive a migration request on the specified testing site.
Realm persistence is an opt-in feature that enables partners to ensure that any re-installations of their apps within a specific duration will persist to the same region that they were previously installed in.
It can be enabled via setting the realmPersistenceDays property in the app descriptor, which specifies how long the previously installed region should be persisted following the app's uninstallation. realmPersistenceDays has a minimum value of 0 (for which the region will not be persisted) and a maximum value of 30 days.
For example, if an app was installed in the EU region with the following snippet in its descriptor, all re-installations of the app will be in the EU region within 10 days of the app being uninstalled.
1 2{ ... "dataResidency": { "realmPersistenceDays": 10, ... }
During installation time, if the product is pinned to a realm, Connect will route all traffic to that realm. If an app doesn't support that particular realm, the traffic will be routed to the global realm instead.
If the product isn't pinned to a realm, Connect will look at where the product is provisioned, known as the 'shard', and will route traffic to the corresponding realm of that shard. However, if the app doesn't support this realm, then Connect will route traffic to the global realm instead.
If an app is uninstalled, information about where the installation was, will be removed. This means a subsequent reinstallation may end up in a different realm depending on whether an app adds support for a new realm or the product is now pinned to a new or different realm.
When an app is upgraded, the app will also continue to be in the realm of when it was installed.
If an administrator pins their product to a realm after an app is installed, the app will remain in its old realm.
For example, if an app is installed into the US realm, then the product is later pinned to a realm, the traffic will still continue to be routed to the US server of the app.
Rate this page: