Reassign VENs in Supercluster Using REST API

When deploying a Supercluster, you might want to “move” workloads that have been paired to one PCE so that they are managed by a different PCE in the Supercluster. For example, you expand your single standalone PCE into a Supercluster and you want to reassign some of your existing VENs to be managed by the nearest PCE. In this case, you can reconfigure the VENs to use a different FQDN to communicate with the proper PCE.

Using the Illumio Agent API (the REST API refers to VENs as “agents” or "managed workloads" or simply "workloads"), you change the target PCE of the workload to the PCE you want to reassign the workload to. The PCE that is currently managing the workload sends the workload the FQDN of the new target PCE; the workload begins heartbeating to and receiving its policy updates from that PCE. The active PCE of the workload is now the same as the target PCE.

Note

Manually moving a VEN to a different PCE using the REST API is subject to the object limit active_agents_per_pce. For more information, see Object Limits and Supercluster.

Active and Target PCE

Before reassigning VENs to another PCE, you need to understand these terms: active PCE and target PCE. These terms correspond to two properties that are added to a workload's VEN on pairing.

active_pce_fqdn: The PCE that is currently managing a workload; namely, the PCE the workload has last heartbeat to.
target_pce_fqdn: The PCE that is configured to manage this workload or the FQDN of the Supercluster (when you configured the supercluster.fqdn property in your runtime_env.yml file).

Workload Reassignment Workflow

This section assumes you are familiar with the basic concepts and usage of the Illumio Core REST API.

Important

Before reassigning workloads to a new PCE, make sure that the active and target PCE are fully operational and at runlevel 5.

The workflow to reassign workloads to a different PCE consists of these general tasks:

GET workloads: To find the HREF of the agent on a workload, get a collection of workloads from the PCE. When you already know the HREF of a workload, you can get an individual instance of that workload, which returns the HREF of the agent that was used to pair that workload.
Identify agent HREF: The workloads' GET response include the agent property, which represents the VENs that are installed on the workloads as part of the pairing process. An agent is identified by its HREF.
Identify active PCE FQDN of agent: The workloads GET schema returns two properties that indicate the FQDN of the PCE that is actively managing the agent (active_pce_fqdn) and a second property that allows you to use a different “target” PCE FQDN (target_pce_fqdn) to manage the agent.
Change target PCE FQDN of agent: Update (PUT) the target_pce_fqdn property so that the VEN can be managed by a different PCE in your Supercluster.

Get Workloads

To get the HREF of an agent (VEN) on a workload, get a collection of workloads. You can GET up to 500 workloads at a time. When you know the HREF of an individual workload, you can get just the single workload.

To get a collection of workloads, you use this URI:

GET [api_version][org_href]/workloads

For example, using curl:

curl -u api_xxxxxxx64fcee809:'xxxxxx5048a6a85ce846a706e134ef1d4bf2
ac1f253b84c1bf8df6b83c70d95'
-H "Accept: application/json" -X GET  https://my.pce.supercluster:443/api/v1/
orgs/7/workloads

Identify Agent HREF in Response

The JSON response from getting workloads provides information about the VEN (“agent”) that was installed when the workload was paired with the PCE. In this response, you identify the workload's VEN (agent) by its HREF.

For example, the section that begins with the agent property shows the HREF of the VEN (href":"/orgs/3/agents/40916). In the response, the active PCE (active_pce_fqdn) and the target PCE (target _pce_fqdn) are the same. This does not change until you perform the reassignment.

"agent": {
            "config": {
                "log_traffic": false,
                "visibility_level": "flow_summary",
                "mode": "illuminated",
                "security_policy_update_mode": "adaptive"
            },
            "href": "/orgs/3/agents/40916",
            "status": {
                "uid": "e6c21a34-ebc2-4cf4-834e-3ec5df31d6ed",
                "last_heartbeat_on": "2016-02-11T12:22:32.91936Z",
                "instance_id": "perf_instance_1289213668111202403
                -1821@1455178338188",
                "managed_since": "2016-02-11T08:13:19.482909Z",
                "fw_config_current": false,
                "firewall_rule_count": null,
                "security_policy_refresh_at": null,
                "security_policy_applied_at": null,
                "security_policy_received_at": null,
                "uptime_seconds": 95819257,
                "status": "active",
                "agent_version": "2.10.0-20150715010305",
                "agent_health_errors": {
                    "errors": [],
                    "warnings": []
                },
                "agent_health": [],
                "security_policy_sync_state": "syncing"
            },
            "active_pce_fqdn": current-pce-fqdn.example.com,
            "target_pce_fqdn": current-pce-fqdn.example.com,

Change Target PCE

When you have the agent HREF, you can update the the target PCE with the PCE FQDN the VEN will use. In your JSON request body, pass the following data:

{
"target_pce_fqdn": "new-pce-fqdn.example.com"
}

The URI for this operation:

PUT [api_version][agent_href]/update

This curl example show how you can pass the target_pce_fqdn property containing the FQDN of the new PCE:

curl -u  api_xxxxxxx64fcee809:'xxxxxxx5048a6a85ce846a706e134ef1d4bf2
ac1f253b84c1bf8df6b83c70d95'
-H "Accept: application/json" -H "Content-Type:application/json" -X PUT
-d '{"target_pce_fqdn":"target-pce.example.com"}' 
https://my.pce.supercluster:443/api/v1/orgs/3/agents/40916/update

Validate VEN Reassignment

To validate that the VEN reassignment was successful, verify the active PCE matches the target PCE. Perform a GET request on the agent again. The target and active PCE FQDN should be the same. When the operation is successful, the response return an HTTP 204 code indicating success.

Note

Reassigning a VEN to a different PCE can take up to 10 minutes to complete.

For example:

"agent": {
            "config": {
                "log_traffic": false,
                "visibility_level": "flow_summary",
                "mode": "illuminated",
                "security_policy_update_mode": "adaptive"
            },
            "href": "/orgs/3/agents/40916",
            "status": {
                "uid": "e6c21a34-ebc2-4cf4-834e-3ec5df31d6ed",
                "last_heartbeat_on": "2016-02-11T12:22:32.91936Z",
                "instance_id": "perf_instance_1289213668111202403
                -1821@1455178338188",
                "managed_since": "2016-02-11T08:13:19.482909Z",
                "fw_config_current": false,
                "firewall_rule_count": null,
                "security_policy_refresh_at": null,
                "security_policy_applied_at": null,
                "security_policy_received_at": null,
                "uptime_seconds": 95819257,
                "status": "active",
                "agent_version": "2.10.0-20150715010305",
                "agent_health_errors": {
                    "errors": [],
                    "warnings": []
                },
                "agent_health": [],
                "security_policy_sync_state": "syncing"
            },
            "active_pce_fqdn": new-pce-fqdn.example.com,
            "target_pce_fqdn": new-pce-fqdn.example.com

Illumio Core 25.2.10 Install, Configure, Upgrade

Reassign VENs in Supercluster Using REST API

Note

Active and Target PCE

Workload Reassignment Workflow

Important

Get Workloads

Identify Agent HREF in Response

Change Target PCE

Validate VEN Reassignment

Note

Search results