Resolving per-artifact fragmentation in component mappings - Spring Application Advisor

Products

• VMware Tanzu Spring Essentials

Issue/Introduction

Running advisor mapping create for lockstep internal modules (such as Apache Kafka) produces fragmented, single-purpose mapping files. Rather than logically grouping these related dependencies, the CLI generates separate files that claim the exact same project slug and shared base coordinates. Consequently, the CLI's strict validation rules detect duplicate coordinates and abort the entire upgrade process.

Environment

 

• Product: VMware Tanzu Spring Application Advisor

• Component: Application Advisor CLI

• Versions: 1.6.x (including 1.6.7)

 

Cause

The Application Advisor CLI currently models lockstep transitive dependencies as entirely separate projects instead of a unified release train. When users attempt to auto-generate mappings for these blocked internal modules, the tool creates individual files that reuse the same slug (e.g., "kafka") and shared coordinates (e.g., kafka-clients). When the tool later merges these custom mappings, its validation rules strictly reject duplicate coordinates across files.

Resolution

Manual Curation (Required Workaround)

Because the CLI cannot currently generate a complete, working set of mappings for large module families, users must avoid the auto-generation commands for these artifacts. Instead, manually author a single, unified mapping file that explicitly groups the dependency family.

Step 1: Create the mappings directory

Run this command from your project's working directory to create the folder:

mkdir -p .advisor/mappings

Step 2: Create the unified mapping file

Create a new file named .advisor/mappings/apache-kafka.json and paste the following unified configuration:

{
  "projects": [
    {
      "slug": "kafka",
      "coordinates": [
        "org.apache.kafka:kafka-clients",
        "org.apache.kafka:kafka-group-coordinator",
        "org.apache.kafka:kafka-server",
        "org.apache.kafka:kafka-server-common",
        "org.apache.kafka:kafka_2.13"
      ]
    }
  ]
}

Step 3: Wire the custom mapping directory to the CLI

Export the folder path so the Advisor engine processes all .json files inside it:

export SPRING_ADVISOR_MAPPING_CUSTOM_0_FILEPATH=.advisor/mappings/

Step 4: Verify the configuration

You can check if your mappings are correctly loaded during your upgrade plan resolution by running:

advisor upgrade-plan get --debug