Analyze project move

This guide describes how to use the Cloud Asset Inventory Analyze Move API to get a detailed report on warnings and blockers from a list of critical policies systems prior to actually moving your project.

Enable APIs

Select or create a project as your API consumer project, enable Cloud Asset API

This consumer project can be different from the project you plan to analyze and migrate. Consumer project will be used to generate credentials to make API request.

The next section describes the required roles and permissions that must be granted on the source project you plan to analyze.

Assign permissions

To perform a project move analysis, you need a role that grants the cloudasset.assets.analyzeMove permission, such as Cloud Asset Viewer or Viewer.

To receive analysis on a service, you also need roles related to those services. These permissions include the following:

• If you want to view the inherited IAM policies from the source project's parent organization resource, you need the resourcemanager.organizations.getIamPolicy permission on the source project's parent organization resource.

• If you want to view the inherited IAM policies from the source project's parent folder, you need the resourcemanager.folders.getIamPolicy permission on the source project's parent folder.

• If you want to view the IAM policies on the project, you need the resourcemanager.projects.getIamPolicy permission on the source project.

• If you want to view the organization policies that are inherited on this project, you need the orgpolicy.policy.get permission on the source project.

• If you want to view the Compute Engine firewall policies that are inherited on this project, you need the compute.organizations.setSecurityPolicy permission on the source folder or organization resource.

• If you want to view the inherited tags on this project, you need the resourcemanager.hierarchyNodes.listEffectiveTags permission on the source project or its ancestor nodes.

Perform the analysis

You can use the Google Cloud CLI or the API to analyze the migration of a resource from its current place in the resource hierarchy.

Note: This API does not perform any checks on the destination organization resource. Even if the destination organization resource specified in the API call does not exist, the analysis of the project to be moved is still performed.

gcloud

To analyze the impacts of migrating a project from its current position in the resource hierarchy, use the gcloud asset analyze-move command:

gcloud asset analyze-move --project=PROJECT_ID \
  (--destination-folder=FOLDER_ID \
    | --destination-organization=ORGANIZATION_ID)

To analyze the impacts of moving a project to a different folder, run the command with --destination-folder:

gcloud asset analyze-move --project=PROJECT_ID \
  --destination-folder=FOLDER_ID

To analyze the impacts of moving a project to a different organization, run the command with --destination-organization:

gcloud asset analyze-move --project=PROJECT_ID \
  --destination-organization=ORGANIZATION_ID

Where:

• PROJECT_ID is the unique project ID of the project you are migrating. For example, --myProject123.

• FOLDER_ID is the numerical folder ID of the destination folder on which to perform the analysis. For example, 45678901123.

• ORGANIZATION_ID is the numerical organization ID of the destination organization on which to perform the analysis. For example, 78901123456.

Note: Exactly one of FOLDER_ID or ORGANIZATION_ID must be specified.

API

To analyze the impacts of migrating a project from its current position in the resource hierarchy without performing the move, use the cloudasset.analyzeMove method:

GET https://cloudasset.googleapis.com/v1/{resource=*/*}: \
  analyzeMove?destinationParent=DESTINATION_NAME

Where:

• resource is the name of the resource on which to perform the analysis. Only project resources are supported, so this must be the Project ID or a Project Number. For example, projects/my-project-id or projects/12345.

• DESTINATION_NAME is the name of the Google Cloud folder or organization resource to reparent the target resource. The analysis will be performed on the impacts of moving the resource to the specified destination parent. The destination must be a folder number or an organization resource number. For example, folders/123 or organizations/123.

Move analysis responses

The response you receive from the Move Analysis API is grouped by service name. Under each service is a list of warnings and blockers applicable to this project migration. Any blockers being returned by this analysis means that the project migration will be blocked at run time if you proceed with the move before resolving them.

Note: Analysis results may not include functionality for services and features that are in preview. If your projects are part of any preview, please refer to that feature's user guide.

Troubleshooting errors

If there is an error returned by the Move Analysis API, it includes a standard gRPC code, as well as a message that describes the reason for the failure of the Move Analysis API to analyze the project.

The following table describes the error codes that could potentially be returned by the Move Analysis API:

Error name	Error code	Description
Invalid argument	3	Returned if you call the API on a project with an invalid argument, such as an incorrect resource name.
Permission denied	7	Returned if you do not have the permissions necessary to perform the analysis or the source project does not exist.
Internal	13	Returned if there is an issue with a call to a policy system such as Identity and Access Management or organization policy. This does not indicate that the migration is not possible, and you can retry the analysis after checking the service for an outage.
Unavailable	14	Returned if an internal system is out of sync. This does not indicate that the migration is not possible, and you can retry the analysis.
Unauthenticated	16	Returned if you have not provided the correct credentials to perform this analysis.

Example error message

The following example demonstrates the error code returned for a user that does not have the cloudasset.assets.analyzeMove permission on the project to be migrated:

{
  "error": {
  "code": 403,
  "message": "Failed to fetch Project: projects/test-project-service-3 to perform
              move analysis.",
  "status": "PERMISSION_DENIED"}
}

Some of the policy systems may fail to analyze the resource move. The following example demonstrates the error returned from the Hierarchical Firewall service when the user does not have compute.organizations.setSecurityPolicy permission on the project to be migrated:

{
  "moveAnalysis": [{
    "displayName": "name hidden",
    "analysis": {
      "warnings": [{
        "detail": "details hidden"
      }]
    }
  }, {
    "displayName": "name hidden",
    "analysis": {
      "warnings": [{
        "detail": "details hidden"
      }]
    }
  }, {
    "displayName": "Hierarchical Firewall",
    "error": {
      "code": 7,
      "message": "Failed to retrieve inherited security policies to perform
                  analysis. Required 'compute.organizations.setSecurityPolicy'
                  permission for {resource ID}"
     }}]
}

What's next

The Move Analysis API provides details that help mitigate blockers and other issues when moving a project from one organization resource to another. For more information about migrating projects between organization resources, see Migrating projects.