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, you need the resourcemanager.organizations.getIamPolicy permission on the source source project's parent organization.

  • 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.

Perform the analysis

You can use the gcloud command-line tool or the API to analyze the migration of a resource from its current place in the resource hierarchy.

gcloud

To analyze the migration implications of a project, use the gcloud asset analyze-move command:

gcloud asset analyze-move --project=PROJECT_ID \
  --DESTINATION_ID

Where:

  • PROJECT_ID is the unique ID of the project you are migrating. For example, projects/12345678901.

  • DESTINATION_ID is the resource type and ID of the destination organization or folder to which you are migrating the project. For example, --destination-folder=45678901123, or --destination-organization=78901123456.

API

To analyze the migration implications of a project, use the cloudasset.analyzeMove method:

GET https://cloudasset.googleapis.com/v1/resource=projects/ \
  PROJECT_NAME:analyzeMove?destinationParent=DESTINATION_ID

Where:

  • PROJECT_NAME is the name of the project you are migrating. For example, foo-project.

  • DESTINATION_ID is the ID of the destination organization or folder to which you are migrating the project. For example, folders/45678901123, or --organizations/78901123456.

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.

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 to another. For more information about migrating projects between organizations, see Project migration.