Machine Migration Between DRP Endpoints: An Explanation

This document explains the architecture and process of migrating machines, their state, profiles, jobs, and workorders from one Digital Rebar Provision (DRP) endpoint to another. It is intended to provide a conceptual understanding of how migration works within a multi-site DRP environment.

For more operational details see How to Migrate a Machine Between DRP Endpoints.

What Happens During Migration?

When a machine is migrated from one DRP endpoint to another, the following occurs:

• The machine object and its associated jobs are migrated to the target endpoint.
• The original machine object on the source endpoint is locked and stripped of active state including tasks, profiles, and params.
• A Meta.redirect-endpoint field is set on the original machine and its jobs, pointing to the new endpoint.
• The jobs on the source endpoint are archived and updated with the Meta.redirect-endpoint field.
• If a profile with the same name exists on both endpoints, the destination's version is used.

Example: Migration and the redirect-endpoint Field

Suppose you have a machine named birdy on drp1 and you migrate it to drp2:

Before Migration

On drp1:

[admin@drp1 ~]$ drpcli machines show Name:birdy
{
    ...
    "Locked": false,
    "Meta": {
        "feature-flags": "change-stage-v2",
        "machine-role": "machine"
    },
    ...
    "Profiles": [
        "example-profile",
        "example-profile2"
    ],
    "Tasks": [
        "stage:hello-world",
        "hello-world"
    ],
    ...
}

After Migration

On drp1, the original machine object is now locked, stripped of tasks and profiles, and includes a redirect-endpoint:

[admin@drp1 ~]$ drpcli machines show Name:birdy
{
    ...
    "Locked": true,
    "Meta": {
        "feature-flags": "change-stage-v2",
        "redirect-endpoint": "https://drp2:8092"
    },
    "Profiles": [],
    "Tasks": [],
    ...
}

On drp2, the machine appears as normal and is now managed there:

[admin@drp2 ~]$ drpcli machines show Name:birdy
{
    ...
    "Locked": false,
    "Meta": {
        "feature-flags": "change-stage-v2",
        "machine-role": "machine"
    },
    ...
    "Profiles": [
        "example-profile",
        "example-profile2"
    ],
    "Tasks": [
        "stage:hello-world",
        "hello-world"
    ],
    ...
}

Jobs Also Get Redirected

The jobs associated with the machine on drp1 are archived and also updated with the redirect-endpoint field:

$ drpcli jobs list Machine=01d8828f-2f7d-4a1c-a1fa-f668274c7c44
[
    {
        "Archived": true,
        ...
        "Meta": {
            "feature-flags": "change-stage-v2",
            "machine-role": "machine",
            "redirect-endpoint": "https://drp2:8092"
        },
        ...
    },
    ...
]

Why Use redirect-endpoint?"

The redirect-endpoint field serves as a pointer for operators and automation, indicating where the machine is now managed. This prevents confusion, avoids duplicate management, and helps maintain a clear migration audit trail.

Profile Conflict Resolution

If a profile with the same name exists on both endpoints, the destination endpoint's profile is used after migration. For example:

On drp1:

[admin@drp1 ~]$ drpcli profiles show conflicting-profile
{
    ...
    "Params": {
        "drp1-only-param": true
    }
}

On drp2:

[admin@drp2 ~]$ drpcli profiles show conflicting-profile
{
    ...
    "Params": {
        "drp2-only-param": true
    }
}

After migration, the machine now on drp2 will use the conflicting-profile as defined on drp2 with the Params as shown above.