> For the complete documentation index, see llms.txt.
Skip to main content

Check out Port for yourself ➜ 

Migrate from AWS Legacy to AWS v3

This page explains how to migrate from the AWS Legacy integration to AWS v3, including your relations, scorecards, and dashboards.

There is no automated migration tool for this transition. We will install AWS v3 alongside AWS Legacy, validate its mappings on temporary blueprints, and then switch to your final blueprints and migrate their catalog dependencies. After validation, you can either retire legacy or keep it for resource kinds that your v3 installation does not support. In the Port application, the v3 integration appears as AWS.

Common use cases​

  • Move your AWS catalog from AWS Legacy to AWS v3 without switching all dependencies at once.
  • Run both integrations in parallel when you still need legacy for some resource kinds.
  • Manage the migration through infrastructure as code (IaC), such as Terraform or Pulumi.

Prerequisites​

  • You have an active AWS Legacy integration and permission to manage integrations, blueprints, scorecards, and dashboards in your factory.
  • You have the AWS permissions required by your chosen AWS v3 installation method.
  • You have saved your legacy mapping, blueprint definitions, entity identifiers and relation values, scorecard definitions, and dashboard configurations so you can compare results and restore your configuration if needed.
  • If you use IaC, you have access to the configuration and state that manage these resources.

Set up data model​

Inventory your legacy dependencies​

  1. Open your AWS Legacy integration on the connectors page and record every configured kind, target blueprint, identifier expression, account, and region.

  2. For each target blueprint, list incoming and outgoing relations, mirror properties, aggregation properties, scorecards, and dashboard widgets that use it.

  3. Compare each kind with the AWS v3 supported resources and resource and property reference. Record the v3 target blueprint, identifier expression, and properties you need.

  4. Check live-event coverage separately. A kind that supports scheduled resyncs may need additional configuration for live events or may only update during resyncs. Confirm coverage for your installed version before moving it.

The default mappings illustrate why you need this inventory:

Resource kindLegacy blueprint and identifierV3 blueprint and identifier
AWS::S3::BucketcloudResource, using .Identifier (the bucket name).s3Bucket, using .Properties.Arn (the bucket's Amazon Resource Name, or ARN).
AWS::EC2::InstancecloudResource, using .Identifier.ec2Instance, using .Properties.InstanceId.

Your custom mappings may differ. Even when an entity identifier stays the same, a relation must target the blueprint that contains the new entity.

Choose which kinds to migrate​

You can run AWS Legacy and AWS v3 side by side. Choose the outcome for each kind:

ApproachWhen to use itFinal state
Full migrationV3 covers all the kinds, properties, and update behavior you require.V3 owns your AWS ingestion, and you remove legacy after validation.
Hybrid parallel runYou still need legacy for kinds or behavior your v3 installation does not support.V3 ingests the migrated kinds, and legacy continues ingesting the remaining kinds.

Assign one integration to each target blueprint and entity identifier pair. If the mappings overlap, use separate target blueprints during the transition so the integrations do not overwrite the same entities. Include shared blueprints such as awsAccount in this review.

Prepare the target blueprints​

Use the kind-specific blueprint definitions in the AWS v3 resource and property reference. Review any existing blueprint with the same identifier before creating or changing it.

For each target blueprint that does not already exist:

  1. Go to the Builder page.

  2. Click + Blueprint.

  3. Click Edit JSON.

  4. Copy the blueprint JSON for the resource kind from the reference and adapt it to your planned properties and relations.

  5. Click Save.

Keep the legacy blueprints while you migrate their consumers. Creating a new blueprint does not move existing entities or their relations.

Prepare temporary validation blueprints​

Before v3 ingests into your final blueprints, create temporary copies using the same Builder steps above. Keep their property schemas consistent with the final blueprints, but give each temporary blueprint a different identifier. For example:

Final blueprintTemporary validation blueprint
awsAccountawsAccountMigrationTemp
s3Buckets3BucketMigrationTemp
ec2Instanceec2InstanceMigrationTemp

Update the temporary blueprints' relation targets to the corresponding temporary blueprints where you want to validate related resources together. For example, point the temporary S3 bucket's account relation at awsAccountMigrationTemp.

Keep your legacy mappings and catalog consumers unchanged during this validation stage. Temporary blueprints let you inspect v3 data before directing it into your final catalog model.

Manage the migration with IaC​

If Terraform or Pulumi manages your Port configuration, make the following changes in that configuration so later deployments preserve the migration:

  1. Bring existing resources under management if needed. Follow the Terraform import instructions or use the corresponding Pulumi resources.

  2. Add the v3 installation and target blueprints as separate resources while keeping the legacy resources. Review the Terraform blueprint example or Pulumi blueprint example for properties and relations.

  3. Apply the migration in stages: create target and temporary blueprints, install v3, validate temporary ingestion, and switch to the final blueprints. Then populate the new relations, rebuild scorecards and dashboards, and remove obsolete resources after validation. Review each plan or preview before applying it.

  4. If you create integrations with Terraform, follow the two-step integration workflow: create the integration without config, then add the mapping in a subsequent apply.

Use your provider's supported resources for scorecards and pages. For configurations you manage in the Port application, apply the same changes there and keep your saved definitions up to date. IaC helps you repeat and review these changes; it does not translate the legacy data model for you.

Install AWS v3 in parallel​

  1. Follow the AWS v3 installation wizard for a hosted or self-hosted deployment. Give the new installation a different identifier from your legacy installation.

  2. Configure the accounts and regions you recorded in your inventory. Review the account discovery settings if you use AWS Organizations.

  3. Keep the legacy deployment running while you configure v3. If you need live events, configure the v3 live-event deployment separately from your legacy event setup.

Update integration mapping​

Start with the v3 mapping examples for each kind and direct initial ingestion to your temporary validation blueprints. Use the identifier expressions and property mappings you plan to use in the final blueprints. Check these against v3 data instead of copying legacy expressions unchanged.

  1. Go to the connectors page of your factory.

  2. Select your AWS integration.

  3. Add the YAML mappings for the kinds you chose to migrate, using the v3 mapping examples. Set each mapping's target to its temporary blueprint and populate its relations using the identifiers of the corresponding temporary entities.

  4. Click Save & Resync to apply the mapping.

Check the sync status. Compare temporary entities with their legacy counterparts by AWS identity, account, and region. Check counts for the same kind and scope, required property values, and relations between temporary entities. Resolve missing properties, permissions, and identifier mismatches before cutover.

Cut over to the final blueprints​

After the temporary mappings pass validation, switch v3 ingestion to the final blueprints from your inventory. Review the integration ownership plan before applying the change so legacy and v3 do not overwrite the same blueprint and entity identifier pairs.

  1. Go to the connectors page of your factory.

  2. Select your AWS integration.

  3. Replace the temporary blueprint identifiers in your YAML mapping with the final blueprint identifiers. Keep the identifier expressions and property mappings you validated, and make sure the final blueprints' relation targets match your final data model.

  4. Click Save & Resync to ingest into the final blueprints.

Verify that the final entities contain the expected properties and resolve their relations. Keep the legacy integration available until you have migrated the consumers and completed the validation checks below.

Repoint relations to the new entities​

For each relation that currently points to a legacy resource, migrate both its blueprint definition and its entity values:

  1. Open the source blueprint on the Builder page and add a relation to the appropriate v3 blueprint. Keep the old relation during the transition. If one legacy relation covered multiple resource kinds, add a separate relation for each new target blueprint.

  2. Update the integration mapping, automation, API request, or IaC definition that populates that relation. Match the old and new resources by AWS identity, and write the new entity identifier to the new relation. For example, a relation to an S3 bucket must use the v3 bucket ARN when you use the default s3Bucket mapping.

  3. Resync the source integration or update the existing source entities to populate the new relation values. Changing a blueprint relation alone does not migrate those values.

  4. Update mirror properties, aggregation properties, filters, and other consumers to use the new relation paths. Verify that the related entities resolve before removing the old relation.

For a hybrid deployment, keep relations to legacy-only kinds. A source blueprint can have relations to both v3 resources and resources that legacy still owns.

Rebuild scorecards and dashboards​

Set up scorecards on the target blueprints​

Recreate scorecards that belong to legacy blueprints on the corresponding v3 blueprints. Adapt their property references, filters, and relation paths to the new model. See manage scorecards for the scorecard JSON structure.

  1. Go to the Builder page.

  2. Search for the target blueprint and select it.

  3. Click on the Scorecards tab.

  4. Click on + New Scorecard.

  5. Click on the {...} button in the top right corner, and choose Edit JSON.

  6. Paste the adapted scorecard JSON. Set its blueprint to the v3 target and use a unique scorecard identifier while the old scorecard still exists.

  7. Click Save.

Compare the new rules and levels on sample entities with the expected legacy results. Keep scorecards for any kinds that remain on legacy.

Rebuild dashboard widgets​

  1. Open each affected dashboard and update or recreate its widgets for the v3 blueprints.

  2. Replace legacy blueprint references, property names, relation paths, and scorecard references in widget datasets, filters, and calculations.

  3. Compare tables, counts, and charts against the same accounts, regions, and kinds. During the parallel run, exclude duplicate legacy representations of migrated resources from your totals.

  4. For a hybrid deployment, keep widgets for legacy-only kinds alongside the v3 widgets.

Let's test it!​

Validate the migration before cleanup​

Complete these checks while both integrations still run. Keep the legacy mappings and catalog dependencies until every check passes.

  1. Run a v3 resync and confirm that all migrated kinds and reconciliation complete successfully in sync status.

  2. Open a migrated entity for each kind. Confirm its AWS identity, properties, account, region, and incoming and outgoing relations.

  3. Open the affected scorecards and dashboards. Confirm that rules evaluate as expected and that counts exclude duplicate legacy representations.

  4. If you enabled live events, make an approved test change to a disposable AWS resource and confirm that v3 updates the matching entity.

If validation fails, keep legacy running and continue using the saved legacy relations and views while you correct the v3 mapping or dependencies.

Retire migrated legacy ingestion​

After the validation checks pass, retire only the legacy ingestion that v3 has replaced:

  1. For a hybrid deployment, retain the legacy mappings for kinds you still need, plus any account or other mappings their relations require. Remove only the mappings for migrated kinds once their consumers use v3. Keep the legacy deployment and event infrastructure needed by the retained kinds.

  2. For a full migration, stop the legacy deployment and its scheduled runs, and disable its legacy event delivery. Check that v3 continues to sync before removing the legacy installation from the connectors page or through your IaC configuration.

  3. Remove obsolete legacy entities, relations, scorecards, and blueprints only after checking that nothing still references them. After verifying final ingestion, remove temporary validation blueprints that no mapping or consumer still uses. Review reconciliation behavior before changing legacy mapping scope; resyncs can delete stale catalog entities.

  4. Remove legacy deployment resources and AWS permissions that no remaining integration uses. Keep the roles and event resources required by v3 and any retained legacy kinds.

Verify ingestion after cutover​

  1. Run a v3 resync and confirm that your migrated entities, relations, scorecards, and dashboards still work after cleanup.

  2. For a hybrid deployment, run a legacy resync and confirm that the retained kinds and their relations still work. For a full migration, confirm that v3 continues syncing with legacy stopped.

Limitations​

  • The migration requires you to adapt mappings, relations, scorecards, and dashboards; installing v3 does not migrate them automatically.
  • Resource and live-event coverage depend on your installed v3 version. Keep legacy for required kinds or behavior until you have verified a replacement.
  • A new blueprint or entity identifier does not carry over the old entity's relation values or historical data automatically.

More relevant guides​