Onboard machines as a single deployment

As an administrator, you can use the Onboarding APIs to onboard unmanaged machines as a single Automation Assembler deployment so that you can manage the machines. To onboard machines, you:

Create an onboarding plan.
Query for unmanaged machines.
Create a bulk deployment that adds the unmanaged machines.
Run the plan.

When you run the plan you can check the plan progress to see if the plan completes successfully and onboards the machines.

The following procedure shows how to onboard machines and create a deployment in VMware Aria Automation without using a cloud template. This is the fastest way to onboard machines. However, to run the Update day 2 action on the deployment after onboarding, you must create the deployment with a cloud template. See How do I add a cloud template to my onboarding plan.

Prerequisites

Verify that all general prerequisites and prerequisites for the Onboarding service have been satisfied. See Prerequisites for API Use Case Examples.
Verify that you have the ID for the cloud account with cloud zones where the machines to be onboarded are located. See Adding Cloud Accounts and Create a Cloud Zone.
Verify that you have the ID for a project with at least one user and with access to the cloud zones. See Create a Project to use in Automation Assembler

Procedure

Assign your project ID variable, for example:

project_id='4c4f8a47-d746-43f4-b88c-ea94ac8bd573'

Assign your cloud ID, for example:

cloud_account_id='0cbc8179-d202-4a30-9460-c25d2653a677'

Create your onboarding plan without placements.

curl -X POST \
    $url/relocation/onboarding/plan \
    -H "Authorization: Bearer $access_token" \
    -H 'Content-Type: application/json' \
    -d '{
      "name": "'<your_plan_name>'",
      "projectId": "'"$project_id"'",
      "endpointIds": [
          "'"$cloud_account_id"'"
      ],
      "usePlacements": false
  }' | jq "."

Note: To create an onboarding plan with placements, set "usePlacements": true. With placement turned on, the onboarded workload considers resource limits defined in your project cloud zones or resource quota plicy and takes longer to run.

Examine the response to verify the status, the project ID, the cloud ID, and to get the documentSelfLink, for example:

{
    "status": "OK",
    "nextRefreshTimeMicros": 0,
    "refreshIntervalMicros": 0,
    "name": "Plan-782",
    "projectId": "4c4f8a47-d746-43f4-b88c-ea94ac8bd573",
    "endpointIds": [
        "0cbc8179-d202-4a30-9460-c25d2653a677"
    ]
    ...
    "documentSelfLink": "/relocation/onboarding/plan/d2010bcd-34f6-4fac-9d67-f7f4c6ec686a"
    ...
}

The value for the documentSelfLink is used for the planLink in subsequent steps.

Use the planLink to discover the compute resources representing unmanaged machines.

curl -X POST \
    $url/relocation/api/wo/query-unmanaged-machine \
    -H "Authorization: Bearer $access_token" \
    -H 'Content-Type: application/json' \
    -d '{
      "planLink": "/relocation/onboarding/plan/d2010bcd-34f6-4fac-9d67-f7f4c6ec686a"
      "expandFields": [
          "id",
          "documentSelfLink",
          "name",
          "powerState",
          "address",
          "creationTimeMicros",
          "expandedTags",
          "tagLinks",
          "endpointLinks"
      ],
      "optionExcludePlanMachines": true
  }' | jq "."

Examine the response to get the snippet for unmanaged machines with "powerState": "ON", for example:

...
"/resources/compute/8bff887d-56fd-3752-bb99-d3f32a35abde": {
    "address": "10.10.10.17",
    "creationTimeMicros": 1717409843457000,
    "documentSelfLink": "/resources/compute/dd646fdc-e6db-3b16-a72e-d1c905f7a9c8",
    "endpointLinks": "/resources/endpoints/aa6a5445-e63a-4659-a277-00073a2645c8",
    "expandedTags": [],
    "id": "5017d984-aa61-e00e-dfa6-a986403c01b8",
    "name": "Machine-76",
    "powerState": "ON",
    "tagLinks": []
    }
"/resources/compute/9bc16a26-bd81-4660-9aa6-6eadfe72456d": {
    "address": "10.10.2.243",
    "creationTimeMicros": 1717409843457000,
    "documentSelfLink": "/resources/compute/8615bbfe-ea90-420a-a1cf-8048ba4271d4",
    "endpointLinks": "/resources/endpoints/2d57f1c4-fbe0-46ce-a061-3a5f1396f37b",
    "expandedTags": [],
    "id": "a6f324e4-101c-33f6-ac51-d9aaaa020123",
    "name": "Machine-25",
    "powerState": "ON",
    "tagLinks": []
    }...

Use the planLink, documentSelfLink, and name to create a single deployment for the unmanaged machines.

curl -X POST \
    $url/relocation/onboarding/task/create-deployment-bulk \
    -H "Authorization: Bearer $access_token" \
    -H 'Content-Type: application/json' \
    -d '{
      "planLink": "/relocation/onboarding/plan/d2010bcd-34f6-4fac-9d67-f7f4c6ec686a",
      "deployments": [
          {
              "name": "'<your_deployment_name>'",
              "resources": [
                  {
                      "link": "/resources/compute/dd646fdc-e6db-3b16-a72e-d1c905f7a9c8",
                      "name": "Machine-76"
                  },
                  {
                      "link": "/resources/compute/8615bbfe-ea90-420a-a1cf-8048ba4271d4",
                      "name": "Machine-25"
                  }
              ]
          }
      ]  
  }' | jq "."

The response shows that the discovered machines have been assigned to the deployment.

{
    "planLink": "/relocation/onboarding/plan/d2010bcd-34f6-4fac-9d67-f7f4c6ec686a",
    "deployments": [
        {
            "planLink": "/relocation/onboarding/plan/d2010bcd-34f6-4fac-9d67-f7f4c6ec686a",
            "name": "Deployment-562",
            "resources": [
               {
                     "link": "/resources/compute/dd646fdc-e6db-3b16-a72e-d1c905f7a9c8",
                     "name": "Machine-76"
               },
               {
                   "link": "/resources/compute/8615bbfe-ea90-420a-a1cf-8048ba4271d4",
                   "name": "Machine-25"
               }
            ],
            "tenantLink": "/core/tenants/dc96003b28356c75",
            "documentVersion": 0,
            "documentUpdateTimeMicros": 0,
            "documentExpirationTimeMicros": 0
        }
    ],
    "tenantLink": "/core/tenants/dc96003b28356c75",
    "documentVersion": 0,
    "documentUpdateTimeMicros": 0,
    "documentExpirationTimeMicros": 0
}

Use the planLink to run the plan and onboard the machines.

curl -X POST \
    $url/relocation/api/wo/execute-plan \
    -H "Authorization: Bearer $access_token" \
    -H 'Content-Type: application/json' \
    -d '{
      "planLink": "/relocation/onboarding/plan/d2010bcd-34f6-4fac-9d67-f7f4c6ec686a" 
  }' | jq "."

Use the planLink to the check the run.

curl -X GET \
    $url/relocation/onboarding/plan/d2010bcd-34f6-4fac-9d67-f7f4c6ec686a \
    -H "Authorization: Bearer $access_token" \
    -H 'Content-Type: application/json' 
 | jq "."

The status in the response changes as the plan moves through executing or updating. If the run fails, the status shows "status": "error".

{
    "status": "OK",
    "nextRefreshTimeMicros": 0,
    "refreshIntervalMicros": 0,
    "name": "Plan-782",
    "projectId": "4c4f8a47-d746-43f4-b88c-ea94ac8bd573",
    "endpointIds": [
        "0cbc8179-d202-4a30-9460-c25d2653a677"
    ],
    "createdBy": "example_admin@example_company.com",
    "enableExtensibilityEvents": true,
    "organizationId": "174adb59-8132-46f0-9cd8-2b2361e9cb2c",
    "customProperties": {},
    "usePlacements": false,
    "isQuick": false,
    "tenantLink": "/core/tenants/dc96003b28356c75",
    "documentVersion": 0,
    "documentKind": "com:vmware:relocation:services:onboarding:plan:OnboardingPlanService:OnboardingPlanState",
    "documentSelfLink": "/relocation/onboarding/plan/d2010bcd-34f6-4fac-9d67-f7f4c6ec686a",
    "documentUpdateTimeMicros": 1718190629415000,
    "documentUpdateAction": "POST",
    "documentExpirationTimeMicros": 0,
    "documentAuthPrincipalLink": "/core/authz/users/example_admin@example_company.com"
}