ESG migration assistant | Endpoint Security Groups | Cisco APIC Security Configuration Guide, Release 6.2(x)

The ESG Migration Assistant analyzes and migrates security contract configurations from endpoint groups (EPGs) to endpoint security groups (ESGs) in bulk.

The ESG Migration Assistant is a utility that analyzes the Cisco APIC configuration, generates a migration plan, applies ESG contract configurations, and removes the original EPG contract configurations.

Separates security policy configuration on ESGs from network forwarding configuration on EPGs.
Supports bulk migration of contract configurations.
Supports integration with Cisco Nexus Dashboard.

Migration phases

The ESG Migration Assistant performs migration in three sequential phases.

Table 1. ESG Migration Assistant phases
Phase	Command	Operation
1	`dryrun`	Analyzes the Cisco APIC configuration and generates a YAML migration plan.
2	`conversion`	Creates the ESG contract configuration defined in the YAML migration plan.
3	`cleanup`	Removes the original contract configuration from the EPGs.

Note

Migrating security contract configurations to ESGs does not deprecate EPGs. EPGs continue to provide network forwarding functions.

Note

The three phases do not need to be completed during the same maintenance window. Between the conversion and cleanup phases, the original EPG contracts and the new ESG contracts are active concurrently. This overlap does not disrupt traffic.

ESG Migration Assistant guidelines and limitations

The ESG Migration Assistant validates the Cisco APIC configuration and fabric resources before migrating endpoint group (EPG) contract configurations to endpoint security groups (ESGs).

Release requirements

The ESG Migration Assistant supports Cisco APIC and leaf switch Release 6.1(4) or later.
Beginning with Cisco APIC Release 6.2(2), the ESG Migration Assistant is included with the Cisco APIC software. For supported earlier releases, download the tool separately from GitHub.
Every leaf switch on which a migrated virtual routing and forwarding (VRF) instance is deployed must run Release 6.1(4) or later.
A mixed-release fabric is supported if every leaf switch associated with a migrated VRF instance meets the minimum release requirement.

Migration scope and mapping

Migrate all VRF instances that participate in the same shared-service relationship together.
The tool does not migrate EPG contract-inheritance relationships directly. It expands inherited contracts into explicit ESG contract relationships.
The tool always maps each microsegmented EPG to a separate ESG.
The tool does not migrate an EPG that has no contracts unless vzAny is enabled on its VRF instance.
During analysis, the tool skips an EPG that is already assigned to an ESG through an EPG selector.

Resource-capacity checks

If policy ternary content-addressable memory (TCAM) utilization exceeds 80 percent on any node, the tool stops the migration. Reduce policy TCAM utilization before running the tool again.
If the combined number of existing global policy control tags (pcTags) and planned ESGs exceeds 10,000, the tool stops the migration. See the Cisco ACI Verified Scalability Guide for supported limits.

Unsupported configurations

The ESG Migration Assistant does not migrate the following configurations:

Taboo contracts
Contracts that use labels
Contracts with the scope set to application-profile

Download and extract the ESG Migration Assistant

Note

Cisco APIC Release 6.2(2) and later include the ESG Migration Assistant in the /data/esg_migration directory. If the Cisco APIC is running one of these releases, skip this task and proceed to ESG Migration Assistant prerequisites and modes .

If the Cisco APIC is running a release from 6.1(4) through 6.2(1), complete the following steps to download and extract the tool.

Procedure

Example:

$ ssh -l admin <apic-ip-address>
                        admin@<apic-ip-address>'s password:

Change to the /data/techsupport directory.
Example:
```
# cd /data/techsupport
```
Download the ESG Migration Assistant package from the ACI ESG Migration Assistant repository .
Copy the ESGMigrationAssistant-<version>.zip file to the /data/techsupport directory on the Cisco APIC.

Extract the package.

Example:

# unzip ESGMigrationAssistant-<version>.zip

Change to the extracted package directory.
Example:
```
# cd ESGMigrationAssistant-<version>
```

Verify that the extracted directory contains the required files.

Table 2. ESG Migration Assistant directory contents
File or directory	Description
`deps/`	Dependencies required by the tool
`ESGMigrationAssistant`	Executable for running the tool directly on the Cisco APIC
`ESGMigrationAssistant.py`	Python script for running the tool from a remote system
`README.md`	Usage instructions
`util.py`	Utility functions used by the tool
`version.txt`	Tool version information

Note

The ESGMigrationAssistant executable and the ESGMigrationAssistant.py script use the same migration logic. Their startup mechanisms differ because one runs on the Cisco APIC and the other connects to the Cisco APIC from a remote system.

Note

At startup, the tool displays Executing from the controller or Executing not from the controller. Verify that the message matches the intended execution environment before continuing.

The ESG Migration Assistant is available in the extracted ESGMigrationAssistant-<version> directory.

What to do next

Run the ESG Migration Assistant as described in ESG Migration Assistant prerequisites and modes .

ESG Migration Assistant prerequisites and modes

Review the prerequisites, and select the migration and contract-cloning modes before running the ESG Migration Assistant.

Before you begin

Verify that the Cisco APIC is running Release 6.1(4) or later.
Verify that every leaf switch on which a migrated virtual routing and forwarding (VRF) instance is deployed is running Release 6.1(4) or later.
Verify that policy ternary content-addressable memory (TCAM) utilization is below 80 percent on every node.
Select a migration mode. See Migration modes .
Select a contract-cloning mode. See Contract-cloning modes .

Run the following phases in order:

dryrun analyzes the configuration and generates a YAML migration plan.
conversion creates the ESG configuration defined in the migration plan.
cleanup removes the original endpoint group (EPG) contract configuration.

Migration modes

Specify the migration mode by using the --mode option with the dryrun command.

Table 3. ESG Migration Assistant migration modes
Mode	Behavior
`optimized` (default)	Groups EPGs into one endpoint security group (ESG) when they have identical contract configurations and belong to the same tenant and VRF instance. The EPGs must also have the same intra-EPG isolation and preferred-group settings. This mode reduces the number of ESGs and policy TCAM entries.
`one-to-one`	Creates one ESG for each EPG. This mode preserves the original security-group boundaries without grouping EPGs.

Note

After migration in optimized mode, endpoints from EPGs grouped into the same ESG can communicate with each other. This behavior might permit traffic that the original EPG design did not permit. Use one-to-one mode to preserve the original security-group boundaries.

Contract-cloning modes

The dryrun command uses the Cisco Nexus Dashboard-compatible mode by default. Include the --disableNdMode option to use native Cisco APIC contract cloning.

Table 4. ESG Migration Assistant contract-cloning modes
Mode	Behavior
Cisco Nexus Dashboard-compatible (default)	Creates one cloned contract for each unique consumer-provider ESG pair. Use this mode for fabrics managed through Cisco Nexus Dashboard.
Native Cisco APIC (`--disableNdMode`)	Shares one cloned contract across multiple consumer-provider ESG relationships. Use this mode for fabrics that are not managed through Cisco Nexus Dashboard.

Note

Both modes produce the same traffic policy. Only the contract-object structure in the Cisco APIC configuration differs.

Note

Include --disableNdMode for every Cisco APIC fabric that is not managed through Cisco Nexus Dashboard.

Phase 1 — Perform an ESG Migration Assistant dry run

Before you begin

Install the ESG Migration Assistant on the Cisco APIC or a remote system that has connectivity to the Cisco APIC.
Obtain valid Cisco APIC credentials.
Select the migration mode and contract-cloning mode.

The dryrun phase analyzes the Cisco APIC configuration and creates a YAML migration plan for review. It does not change the Cisco APIC configuration.

Use the following syntax when running the tool on the Cisco APIC:

ESGMigrationAssistant dryrun \
                --outYaml <output_yaml_file> \
                [--mode {optimized|one-to-one}] \
                [--tenantdns <tenant_dn_list>] \
                [--tenantRegex <tenant_name_patterns>] \
                [--vrfdns <vrf_dn_list>] \
                [--prefix <prefix>] [--suffix <suffix>] \
                [--targz <input_file> | --json <input_file> | --xml <input_file>] \
                [--disableNdMode] [--showStats]

Use the following syntax when running the tool from a remote system:

python ESGMigrationAssistant.py dryrun \
                --apic <apic_ip> \
                --username <username> \
                --password <password> \
                --outYaml <output_yaml_file> \
                [--mode {optimized|one-to-one}] \
                [--tenantdns <tenant_dn_list>] \
                [--tenantRegex <tenant_name_patterns>] \
                [--vrfdns <vrf_dn_list>] \
                [--prefix <prefix>] [--suffix <suffix>] \
                [--targz <input_file> | --json <input_file> | --xml <input_file>] \
                [--disableNdMode] [--showStats]

Table 5. ESG Migration Assistant dry-run parameters
Parameter	Description
`--outYaml`	Specifies the YAML file in which to save the migration plan. This parameter is required.
`--mode`	Specifies the `optimized` or `one-to-one` migration mode. The default is `optimized`.
`--tenantdns`	Includes all virtual routing and forwarding (VRF) instances in the specified tenants. Enter a comma-separated list of tenant distinguished names (DNs) without spaces, such as `uni/tn-T1,uni/tn-T2`.
`--tenantRegex`	Includes tenants whose names match a comma-separated list of names or regular expressions. Enclose the value in quotation marks, such as `"T1,T2,Prod.*,Test[0-9]+"`.
`--vrfdns`	Includes the specified VRF instances. Enter a comma-separated list of VRF DNs without spaces, such as `uni/tn-T1/ctx-ctx1,uni/tn-T2/ctx-ctx2`.
`--prefix`	Adds the specified prefix to cloned contract and endpoint security group (ESG) names.
`--suffix`	Adds the specified suffix to cloned contract and ESG names. The default suffix is `_e`.
`--targz`, `--json`, or `--xml`	Specifies an existing configuration snapshot in the corresponding file format. If no input file is specified, the tool prompts you to create a snapshot or select an existing snapshot.
`--disableNdMode`	Enables native Cisco APIC contract cloning instead of Cisco Nexus Dashboard-compatible cloning.
`--showStats`	Displays fabric-configuration statistics before starting the analysis.
`--apic`	Specifies the Cisco APIC IP address or hostname. This parameter is required when running the tool remotely.
`--username`	Specifies the Cisco APIC username. This parameter is required when running the tool remotely.
`--password`	Specifies the Cisco APIC password. This parameter is required when running the tool remotely.

Note

The --tenantdns, --tenantRegex, and --vrfdns filters use union logic. A VRF instance that matches any specified filter is included. If no filter is specified, the tool analyzes the entire fabric configuration.

Procedure

Run the dryrun command with the required options.

Note

If you do not specify an input file, create a fresh configuration snapshot when prompted so that the analysis reflects the current fabric configuration. When the tool runs remotely, it creates the snapshot on the Cisco APIC rather than on the remote system.
Example:

For example, run the following command on the Cisco APIC:
```
# ESGMigrationAssistant dryrun --outYaml migration-plan.yaml
```
Or run the following command from a remote system:
```
$ python ESGMigrationAssistant.py dryrun \
                        --apic <apic_ip> \
                        --username <username> \
                        --password <password> \
                        --outYaml migration-plan.yaml
```

If you selected optimized mode, review the warning and confirm whether to continue.

The chosen run mode is optimized where application EPGs and external EPGs
                        with identical contract layout are grouped together into the same ESG.
                        This mode reduces the number of ESGs created and reduces TCAM utilization,
                        but it may allow unintended communication between the grouped EPGs.
                        Do you want to continue? (yes/no)

Review the generated YAML migration plan.
Verify the following information:
- VRF instances included in the migration
- ESGs to create and the endpoint groups (EPGs) assigned to each ESG
- Default ESG names
- Contracts provided and consumed by each ESG
- External subnet selectors assigned to each ESG
- Leaked routes required for shared-service relationships
- Contracts to clone and their new names
Note

In optimized mode, ESG names use the format ESG_<tenantName>_<appProfileName>_<incrementalCount>. In one-to-one mode, ESG names use the format <prefix><epgName><suffix>.

Note

The YAML migration plan does not include vzAny or in-band EPGs. The tool processes these objects automatically during the conversion phase.
Edit the YAML migration plan if changes are required.

You can modify ESG names, cloned contract names, EPG grouping and assignments, and route-leaking entries. The conversion phase applies the configuration defined in the YAML file.

Note

Edit the YAML file only when necessary. Before starting the conversion phase, verify that all changes are complete, accurate, and internally consistent. Incorrect or incomplete changes can cause configuration errors or unexpected policy behavior.

The YAML migration plan is ready for use in the conversion phase. The dry run does not change the Cisco APIC configuration.

What to do next

After verifying the YAML migration plan, proceed to the ESG Migration Assistant conversion phase.

Phase 2 — Apply an ESG migration plan

Before you begin

Complete the ESG Migration Assistant dryrun phase.
Review and finalize the YAML migration plan generated during the dry run.
Obtain valid Cisco APIC credentials when running the tool from a remote system.

The conversion phase applies the configuration defined in the YAML migration plan. During this phase, the ESG Migration Assistant creates ESGs, clones and assigns contracts, configures route leaking, and installs selectors that change endpoint security classification from endpoint groups (EPGs) to ESGs.

Use the following syntax when running the tool on the Cisco APIC:

ESGMigrationAssistant conversion \
                --inYaml <yaml_file> \
                [--configStrategy {interactive|vrf}] \
                [--noConfig] \
                [--outputFile <output_file.xml|output_file.json>]

Use the following syntax when running the tool from a remote system:

python ESGMigrationAssistant.py conversion \
                --apic <apic_ip> \
                --username <username> \
                --password <password> \
                --inYaml <yaml_file> \
                [--configStrategy {interactive|vrf}] \
                [--noConfig] \
                [--outputFile <output_file.xml|output_file.json>]

Table 6. ESG Migration Assistant conversion parameters
Parameter	Description
`--inYaml`	Specifies the YAML migration plan generated during the `dryrun` phase. This parameter is required.
`--configStrategy`	Specifies the `interactive` or `vrf` configuration strategy. The default is `interactive`.
`--noConfig`	Displays the proposed configuration without applying it to the Cisco APIC.
`--outputFile`	Saves the proposed configuration in XML or JSON format. Use an `.xml` or `.json` file extension. The default file is `output.xml`.
`--apic`	Specifies the Cisco APIC IP address or hostname. This parameter is required when running the tool remotely.
`--username`	Specifies the Cisco APIC username. This parameter is required when running the tool remotely.
`--password`	Specifies the Cisco APIC password. This parameter is required when running the tool remotely.

Procedure

Preview the proposed configuration before applying it.

Example:

For example:

# ESGMigrationAssistant conversion --inYaml migration-plan.yaml --noConfig

Run the conversion command with the finalized YAML migration plan.

Note

If you edited the YAML migration plan after the dry run, specify the edited file with --inYaml.

Example:

For example, run the following command on the Cisco APIC:

# ESGMigrationAssistant conversion --inYaml migration-plan.yaml

Or run the following command from a remote system:

$ python ESGMigrationAssistant.py conversion \
                        --apic <apic_ip> \
                        --username <username> \
                        --password <password> \
                        --inYaml migration-plan.yaml

Review the precheck results.
The tool performs the following checks before applying any configuration:
- YAML validation: Verifies the file format, object names, required keys, and duplicate entries.
- Release validation: Verifies that the Cisco APIC and each leaf switch associated with a migrated virtual routing and forwarding (VRF) instance meet the Release 6.1(4) minimum requirement. The tool stops if a required node does not meet the requirement.
- Policy ternary content-addressable memory (TCAM) validation:
  - A node with utilization greater than 80 percent is classified as critical. If a migrated VRF instance is deployed on a critical node, the tool stops.
  - A node with utilization greater than 50 percent is classified as a warning. If a migrated VRF instance is deployed on a warning node, the tool continues with a modified migration strategy.
- Scalability validation: Verifies that the combined number of existing global policy control tags (pcTags) and planned ESGs does not exceed the operational limit of 10,000. Each ESG consumes one global pcTag. The system supports 16,384 global pcTags, but the operational limit is 10,000.
At the rollback-snapshot prompt, enter Yes to create a snapshot before applying the configuration.
You can enter one of the following responses:
- Yes: Creates a rollback snapshot and continues.
- No: Continues without creating a snapshot. Only previously created snapshots are available for rollback.
- Quit: Stops the conversion.
Note

Create a rollback snapshot before continuing so that you can restore the pre-migration configuration if traffic is disrupted.
If prompted, select the configuration strategy.
- interactive (default): Applies one component at a time. At each prompt, enter Yes to apply the current item, Yes to all (A) to apply the remaining items of the same type, or No to skip the item.
- vrf: Applies the configuration for all EPGs in a VRF instance in one transaction. This strategy reduces the number of Cisco APIC operations and shortens the traffic-cutover interval.
Note

Use the interactive strategy for an initial migration or when each configuration change requires separate verification.
Confirm the configuration actions as prompted.
The tool performs the following actions in order:
1. Creates the ESGs for each VRF instance.
2. Configures leaked-route subnets for shared-service relationships.
3. Clones contracts using the names defined in the YAML migration plan.
4. Assigns the cloned contracts to ESGs as provider and consumer relationships.
5. Migrates intra-EPG and vzAny contract relationships to the ESGs.
6. Installs EPG selectors on ESGs to change endpoint security classification from EPGs to ESGs. For Layer 3 Outside (L3Out) external EPGs, the tool installs external subnet selectors.
7. Verifies that the pcTag for each migrated EPG is updated on the leaf switches before proceeding to the next EPG.
8. Performs a final policy TCAM utilization check.
Note

The first five actions do not cause traffic disruption. Traffic cutover occurs when the tool installs the EPG or external subnet selectors.
If a problem occurs, enter Quit at a prompt and review the available rollback snapshots.
- If a configuration push fails, quit without rolling back, investigate the failure, correct the problem, and run the conversion again.
- If traffic is disrupted, quit and restore the snapshot created at the beginning of the conversion session.
After the conversion finishes, verify the migrated environment.
- Verify traffic flow between all migrated endpoints.
- Verify that application services operate as expected.
- Verify that ESG contracts enforce the expected security policy.
Note

The original EPG contracts and the new ESG contracts remain active concurrently after conversion. You can perform the cleanup phase in a separate maintenance window after completing migration verification.

The ESG configuration defined in the YAML migration plan is applied, and endpoint security classification is migrated to ESGs. The original EPG contracts remain active until the cleanup phase removes them.

What to do next

After verifying endpoint connectivity, application operation, and ESG policy enforcement, proceed to the ESG Migration Assistant cleanup phase.

Phase 3 — Clean up original EPG contracts

Before you begin

Complete the ESG Migration Assistant conversion phase.
Verify endpoint connectivity, application operation, and endpoint security group (ESG) policy enforcement.
Obtain valid Cisco APIC credentials when running the tool from a remote system.

The cleanup phase removes the original contract relationships from migrated EPGs and optionally deletes contracts that are no longer referenced by an EPG or ESG.

For subnets used in shared-service relationships, the tool removes the shared-service attribute but retains the subnet configuration.

Use the following syntax when running the tool on the Cisco APIC:

ESGMigrationAssistant cleanup \
                [--configStrategy {interactive|vrf|global}] \
                [--noConfig] \
                [--outputFile <output_file.xml|output_file.json>]

Use the following syntax when running the tool from a remote system:

python ESGMigrationAssistant.py cleanup \
                --apic <apic_ip> \
                --username <username> \
                --password <password> \
                [--configStrategy {interactive|vrf|global}] \
                [--noConfig] \
                [--outputFile <output_file.xml|output_file.json>]

Table 7. ESG Migration Assistant cleanup parameters
Parameter	Description
`--configStrategy`	Specifies the `interactive`, `vrf`, or `global` cleanup strategy. The default is `interactive`.
`--noConfig`	Displays the proposed cleanup actions without applying them to the Cisco APIC.
`--outputFile`	Saves the proposed cleanup configuration in XML or JSON format. Use an `.xml` or `.json` file extension. The default file is `output.xml`.
`--apic`	Specifies the Cisco APIC IP address or hostname. This parameter is required when running the tool remotely.
`--username`	Specifies the Cisco APIC username. This parameter is required when running the tool remotely.
`--password`	Specifies the Cisco APIC password. This parameter is required when running the tool remotely.

Procedure

Preview the cleanup actions before applying them.

Example:

For example:

# ESGMigrationAssistant cleanup --noConfig --outputFile cleanup-preview.xml

Run the cleanup command.

Example:

For example, run the following command on the Cisco APIC:

# ESGMigrationAssistant cleanup --configStrategy interactive

Or run the following command from a remote system:

$ python ESGMigrationAssistant.py cleanup \
                        --apic <apic_ip> \
                        --username <username> \
                        --password <password> \
                        --configStrategy interactive

At the rollback-snapshot prompt, enter Yes to create a snapshot before applying the cleanup configuration.

Note

Create a rollback snapshot so that you can restore the pre-cleanup configuration if a problem occurs.
If prompted, select the cleanup strategy.
- interactive (default): Removes contract relationships and shared-service subnet attributes from one EPG at a time, with confirmation before each change.
- vrf: Removes contract relationships and shared-service subnet attributes for all EPGs in one virtual routing and forwarding (VRF) instance in a single transaction. After removing the EPG contract relationships, the tool processes unreferenced contracts by tenant.
- global: Previews cleanup actions across all VRF instances. After processing the EPG contract relationships, the tool processes unreferenced contracts by tenant.
Note

Use the interactive or vrf strategy for live cleanup. Use the global strategy only with --noConfig.
Confirm the cleanup actions as prompted.
The tool performs the following actions:
1. Removes the original contract relationships from each migrated EPG.
2. Removes the shared-service route-leaking attributes from the applicable EPG subnets without deleting the subnet configuration.
3. Removes the esg_migration:cleanup_required annotation from each migrated EPG selector, in-band EPG, and vzAny object.
4. Identifies contracts that are no longer referenced by an EPG or ESG and prompts you to delete them.
Note

During the conversion phase, the tool adds an annotation with the key esg_migration and the value cleanup_required to each migrated EPG selector, in-band EPG, and vzAny object. The cleanup phase uses these annotations to limit changes to objects included in the migration and removes each annotation after processing the object.
If a problem occurs, enter Quit at a prompt and restore the snapshot created at the beginning of the cleanup session.
Verify the environment after cleanup.
- Verify traffic flow between the migrated endpoints.
- Verify that ESG contracts enforce the expected security policy.
- Verify that the original EPG contract relationships are removed.
- Verify that the required subnet configurations remain present.

The original EPG contract relationships, migration annotations, and confirmed unreferenced contracts are removed. ESG contracts remain active, and the required subnet configurations are retained.

Verify ESG migration updates in Cisco APIC

Before you begin

Complete the ESG Migration Assistant cleanup phase.

Use the Cisco APIC GUI to verify that the migration configuration is complete and that the migrated applications operate as expected.

Procedure

Navigate to Tenants > tenant-name > Application Profiles > application-profile-name > Endpoint Security Groups .
Verify the following ESG configuration:
- All expected ESGs are present.
- Each ESG contains the expected endpoint group (EPG) selectors.
- Each ESG has the expected provider and consumer contract relationships.
Navigate to Tenants > tenant-name > Networking > VRFs > vrf-name .

Verify that the route-leaking configuration is correct for every virtual routing and forwarding (VRF) instance that participates in a shared-service relationship.
Navigate to Tenants > tenant-name > Contracts .
Verify the following contract configuration:
- The cloned ESG contracts are present and use the expected names.
- The original EPG contracts no longer have provider or consumer relationships.
Navigate to Fabric > Inventory > leaf-node > Contracts .
Verify the following information for each applicable leaf switch:
- The expected security rules are deployed.
- The policy control tags (pcTags) for the migrated EPGs are updated.
Verify traffic flow between the migrated endpoints and test the affected application services.

Note

If verification identifies a problem, use the Cisco APIC configuration rollback capability to restore the snapshot created at the beginning of the conversion or cleanup phase.

The ESG migration is verified when the expected policies are present and the migrated endpoints and application services operate correctly.