Skip to main content

Illumio Security Policy Guide 25.4

  • Illumio Security Policy Guide 25.4
  • Workloads
  • Update Workload Labels in Bulk

Update Workload Labels in Bulk

workload-import-export.png

This section describes how to perform bulk operations on labels using the Import / Export feature available on the Workloads List Page. With this feature, you can:

  • You can export a CSV or JSON file containing information about the Illumio labels assigned to your workloads. You can also export other information about your workloads.

  • Import changes to your workload labels using either the CSV file you exported from the PCE or your own CSV file. You can use the Import feature to do the following:

    • Create new labels of existing label types and assign them to workloads. (Labels you create using Import are assigned to the workloads you specify in the CSV file. You can't use Import to create an unassigned label.)

    • Change a label assigned to a workload.

    • Unassign a label from a workload.

About the Export File

File format

You can export the file in these formats:

  • CSV: This format is convenient if you use the same file to import label updates to the PCE. Only CSV files can be imported to the PCE.

  • JSON: This option exports workload data in a JSON file. It can't be imported to the PCE.

Columns

workloads-csv-column-header.png

By default, the exported CSV file has the following columns:

Note

The href and hostname columns must occupy the first and second columns from the left, respectively, and column headers should not be changed. Label column headers should not be changed, but the columns can be in any order.

  • First column: href

  • Second column: hostname

  • label: role

  • label: app

  • label: env

  • label: loc

Rows

With the exception of the header row (the top row), each row in the import file corresponds to a workload on the PCE.

workloads-csv-rows.png

CSV file requirements

Whether you're using a file exported from the PCE or your own *.csv file, the file you intend to import to the PCE must meet the following requirements:

  • The file must be in a *.csv format.

  • The first column header must be href

  • The second column header must be hostname.

  • The file doesn't need a label column for every label type defined in the PCE Label Settings (Settings > Label Settings).

  • If you're attempting to create new labels, ensure they don't exist in your Illumio instance. If the label already exists, an error will occur, and an error message will appear.

  • You can include label types other than Role, Application, Environment, and Location if they are already defined in the PCE Label Settings.

  • Blank cells in the import file are ignored.

  • Up to 1000 import rows per CSV are supported.

Customizing the file

If custom label types are defined in Settings > Label Settings on the PCE, the exported file will include columns corresponding to those Label Types. For example, if your organization defines custom label types for OS and city, the exported file will include corresponding columns.

label-settings.png
export-file-custom-labels.png

Procedure

STEP 1: Export Workload Information

Tip

You can skip the Export step if you plan to prepare your own CSV file for importation to the PCE. See Step 1

You can use the Export feature to create and download a file to your local computer for one or both of the following reasons:

  • Prepare for importing bulk updates. In the exported file, specify the updates you want to make to Workload labels, as described in STEP 2: Prepare the CSV file for import. Then, import the file to the PCE, as described in Step 3.

  • Capture workload information—export data about your workloads in a text file for informational purposes.

  1. In the left navigation, click Servers & Endpoints > Workloads.

  2. On the Workload list page, click Export in the upper right corner.

  3. In the Export Workloads dialog box, configure settings:

    • Export:

      • All Workloads: Select if you want the exported file to include all Workloads. If no filters are applied, only this option is available.

      • Filtered Workloads: This option is available only if one or more filters are applied to the list of workloads. Select if you want the exported file to include only the filtered list of Workloads. Otherwise, select All Workloads.

    • Columns:

      • All Columns: Select if you want the exported file to include all columns in the Workload List Page, including hidden columns. Note: While the exported file includes all columns, only updates you make to data in the label columns will take effect when you import the file to the PCE. Changes to data in other columns, if any, are ignored.

      • Labeling Columns: Select if you want the exported file to include only the label columns in the Workload List Page.

    • File Format:

      • CSV: Select CSV if you plan to use this file to import label updates to the PCE. Only CSV files can be imported to the PCE.

      • JSON: This option is not used for updating labels. It exports workload data in a JSON file, JSON files cannot be imported to the PCE.

  4. Click Export. The file is sent to your Downloads folder.

STEP 2: Prepare the CSV File for Import

Here's how to prepare the CSV file for creating, assigning, updating, and unassigning labels during import.

  1. Open the CSV file located in your Downloads folder and modify it in any of the following ways:

    • Assign a new or change an existing label.

      In the appropriate label column and workload row, enter a label name or change an existing label name for each workload that you want to have the new or a changed label.

    • Unassign labels

      In the appropriate label column and workload row, replace the name you want to unassign with any combination of alphanumeric or special characters. Later, in STEP 3: Update Workload Labels Using Import, you'll enter the exact string in "Remove the existing label" if the imported label matches the string listed below. Also, unassigning a label from a given workload doesn't delete the label for use with other workloads in the PCE.

      Note

      Simply deleting the label name from the CSV file and then importing the file to the PCE does not unassign the label from the workload.

      As described in the above step, you must replace the label name in the CSV file with a string that you'll also enter in the Import a CSV to edit workload labels dialog box, as described in STEP 3: Update Workload Labels Using Import. If the strings don't match when you perform the import, an error occurs, and the label isn't unassigned.

  2. Save the CSV file.

STEP 3: Update Workload Labels Using Import

The Import feature sends a CSV file to the PCE to update workload labels on your PCE. You can upload a CSV exported from the PCE (STEP 1: Export Workload Information) or prepare and upload your own CSV file.

  1. Prepare the CSV file for import (STEP 2: Prepare the CSV File for Import).

  2. If you have not already done so, log in to the PCE.

  3. In the left navigation, go to Servers & Endpoints > Workloads.

  4. On the Workload list page, click Import in the upper-right corner.

  5. In the Import a CSV to edit workload labels dialog box, click Choose File and select the CSV file you want to import to the PCE.

  6. Select one or both of the following options:

    • Create labels if they don't already exist

      This option allows you to create new labels of an existing label type and assign them to workloads you specified in the CSV file. Available label types are defined in Settings > Label Settings.

    • Remove the existing label if the imported label matches the string listed below

      This option allows you to unassign a label from workloads you specified in the CSV file in STEP 2: Prepare the CSV File for Import. Enter the exact string in this field that you entered in the CSV file as described in STEP 2. If the strings don't match when you perform the import, an error occurs, and the label isn't unassigned.

      Note

      Simply entering a string in this field and importing the CSV file to the PCE does not unassign the label from the workload. You must enter the exact string in this field in the CSV file.

      If the strings don't match when you perform the import, an error occurs, and the label isn't unassigned. Also, unassigning a label from a given workload doesn't delete the label for use with other workloads in the PCE.

  7. Click Preview Changes.

  8. Review the proposed changes in the Preview Changes message.

  9. (Optional) Click Review to see the impact of your changes before you complete the import process. Any new labels you created appear in the New Labels list. A copy button allows you to copy the details into your buffer.

    Click Back to return to the Preview Changes message.

  10. Click Save. The file is imported into the PCE.

  11. Click Refresh to see the label changes reflected in the workloads list.

  12. If you entered a string in the CSV file to remove an existing label, delete the string from the file and then save the file. Otherwise, if you import the file again, the PCE will interpret the string as a label you want to add to a workload.