Prepare your cloud app for Forge container services migration

This page explains how to prepare your cloud app for migration by processing events.

Events

The Forge container service, endpoint, and trigger modules that you implement will allow the app migration platform to send information about specific migration events that take place on your server app.

Add Forge container service and trigger to the manifest

Define a service, an endpoint, and a trigger to process migration events.

See an example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
modules:
  trigger:
    - key: migration-trigger
      endpoint: migration-event
      events:
        - avi:ecosystem.migration:triggered:listener
        - avi:ecosystem.migration:uploaded:app_data
        ...

  endpoint:
    - key: migration-event
      service: migration-service
      route:
        path: /migration-events

services:
  - key: migration-service
    containers:
      - key: migration-container
        tag: ${TAG}
        resources:
          cpu: "1"
          memory: "2Gi"
        health:
          type: http
          route:
            path: /health

The app migration platform sends each event to your container service as an HTTP POST request to the endpoint route.path.

Refer to the event types for all the events that you can listen for and their associated payloads.

Processing events

When processing events it is important to keep in mind the following:

• Event acknowledgement - you must call status API for avi:ecosystem.migration:uploaded:app_data events within 15 minutes of processing the last event or uploading new data from the server app (whichever occurs later).
• Events are not ordered - the platform may send events in a different order e.g. avi:ecosystem.migration:uploaded:app_data may appear before avi:ecosystem.migration:triggered:listener.
• Validate the event payloads and return an error response if validation fails - this will help you monitor for failed invocations and failed invocations will be retried.
• Containers can be terminated and replaced at any time. Do not rely on in-memory state to track which events you have processed, and only acknowledge an event once its data has been processed.

Event types

You can add the following events to your Forge trigger.

Payload

This is the data that is sent in the body of the request to your container service endpoint.

Example payload

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "eventType": "avi:ecosystem.migration:uploaded:app_data",
  "transferId": "3f3a47f2-a6a2-4204-84bb-d0fc504c9dc6",
  "migrationDetails": {
    "migrationId": "403c4f71-a0d1-4a63-97a8-487d18691c46",
    "migrationScopeId": "0ba07dd9-3804-4600-9102-fa6e1efeab08",
    "createdAt": 1723111376499,
    "cloudUrl": "https://your-customer-cloud-site.atlassian.net",
    "name": "Migration Plan Name",
    "testMigration": false
  },
  "key": "e094ca53-3747-4541-b263-0bf7b56a5bca",
  "label": "file-label-you-used",
  "serverAppVersion": "1.0",
  "messageId": "53f88ea7-a2d2-4dd2-9f36-2d8c43401b11"
}

Forge migration REST API

Refer to the REST API documentation for the available endpoints and their usage.

Authentication

Requests to the egress sidecar must contain a forge-proxy-authorization header. Use as=app for all app migration platform requests. There are two ways to identify the context of the request:

For more detail, refer to Forge Container services API contract and Call a containerised service without an invocation ID.

The Forge Container services sidecar authenticates inbound requests to your service, so you do not need to verify the requests yourself.

Example

The following example handles every event sent to the endpoint, and acknowledges only avi:ecosystem.migration:uploaded:app_data events after processing them. It is an excerpt, and uses Node.js with Express.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
import express from "express";

const app = express();
app.use(express.json());

app.post("/migration-events", async (req, res) => {
  const event = req.body;
  const invocationId = req.header("x-forge-invocation-id");

  // Validate the payload and process the event
  if (!event.transferId || !event.messageId) {
    return res.status(400).json({ error: "Invalid migration event" });
  }

  // Only uploaded app data needs to be acknowledged. Return 200 for all other event types.
  if (event.eventType !== "avi:ecosystem.migration:uploaded:app_data") {
    return res.json({ message: `Ignored ${event.eventType}` });
  }

  // ... download and import the data identified by event.key ...

  const response = await fetch(
    `${process.env.FORGE_EGRESS_PROXY_URL}/atlassian/app/migration/forge/v1/message/${event.transferId}/status`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "forge-proxy-authorization": `Forge as=app,id=${invocationId}`,
      },
      body: JSON.stringify({ status: "SUCCESS", messageIds: [event.messageId] }),
    }
  );

  if (!response.ok) {
    // A non-2xx response will cause the event to be sent again
    return res.status(502).json({ error: `Status update failed: ${response.status}` });
  }
  return res.json({ message: `Successfully processed ${event.messageId}` });
});

app.listen(process.env.SERVER_PORT);

Error handling