Creating GCP Roles and Service Accounts

Overview

In order for the Velostrata operations to execute properly, there are a number of roles and service accounts that need to be created in GCP first. In GCP, roles are a set of permissions, and service accounts are assigned these roles, in this case within the context of either a project or a service account. For a detailed explanation of the permissions in each role, you can view the YAML files that we'll provide to create them. For more information on what each service account will entail, please read below: 

  • Velostrata Management Service Account (velos-gcp-mgmt-sa):
    Enables Velostrata to create objects within the GCP project(s) and then manage those objects based on the Velostrata management tasks that are invoked. For example, this service account will be used to create all the elements that a CloudExtension needs (compute instance creation, cloud storage buckets created, etc.). These are all tasks which are invoked in the GCP project, which velostrata needs permission to perform [via this service account].

  • Velostrata Cloud Extension Service Account (velos-gcp-ce-sa):
    Will leverage a subset of GCP storage permissions, such that it is allowed to read/write storage objects from cloud storage, manage those objects, as well as data requests between the Velostrata cache and cloud storage. All tasks are related to getting things from the source (on-prem or another cloud) and into GCP and would include operations like data reads and data commits, for example.

  • Velostrata Project Worker Service Account (velos-gcp-worker-sa):
    Leverages the same subset of GCP storage permissions as velos-ce-sa, but this service account is only used when Velostrata’s ‘prepare to detach’ operation is invoked. This service account will be used by the Velostrata Worker Auxiliary VM which will prepare the native storage in the cloud and copy data from the cloud storage bucket into the disks that are attached to the Velostrata Worker Auxiliary VM.

How these service accounts are defined will also vary based on your project architecture within GCP. If you are using a standalone project, these roles and service accounts are all created in that standalone project. If you are using an organization with multiple projects, all of the roles will be created within the organization but the service accounts and assignments will take place in various project locations. 

Instructions

Standalone Project

For a standalone project, you will create three service accounts (listed above in the overview section) and three roles and assign the appropriate roles to service accounts. 

1. Create the Velostrata Roles within GCP at the Project level

A. Open an elevated command prompt so you can use the GCP SDK (if you have not installed GCP SDK, please refer to this article) to run the following command while replacing the appropriate parameters (in blue) with your own environment's values:

gcloud auth login login@google.com --no-launch-browser --brief

B. Download this zip file which contains the YAML files needed to create these roles. 

C. Unzip the file and save to a directory you'll remember.

D. Execute the following commands while replacing the appropriate parameters (in blue) with your own environment's values

gcloud iam roles create "velos_mgmt_role" --project projectID --file ./velos_gcp_org_mgmt_role.yaml --no-user-output-enabled --quiet 

gcloud iam roles create "velos_ce_role" --project projectID --file ./velos_gcp_org_ce_role.yaml --no-user-output-enabled --quiet 

gcloud iam roles create "velos_worker_role" --project ProjectID --file ./velos_gcp_org_worker_role.yaml --no-user-output-enabled --quiet


2. Create the velos-gcp-mgmt-sa service account in GCP

A. Execute the following commands in your elevated command prompt while replacing the appropriate parameters (in blue) with your own environment's values:

gcloud config set project projectId 

gcloud iam service-accounts create "velos-gcp-mgmt-sa" --display-name "Velos-gcp-mgmt-sa"


3. Assign velos_mgmt_role (created in step 1, above) to the velos-gcp-mgmt-sa service account

A. Execute the following commands in your elevated command prompt while replacing the appropriate parameters (in bold italics) with your own environment's values:

Note: ProjectID is the ID of the same project you used in step 2 when creating velos-gcp-mgmt-sa.

gcloud projects add-iam-policy-binding ProjectID --member serviceAccount:"velos-gcp-mgmt-sa@projectID.iam.gserviceaccount.com" --role "velos_mgmt_role" --no-user-output-enabled --quiet


4. Create the velos-gcp-ce-sa service account in GCP

You will create this account in the project where you plan to deploy the Velostrata Cloud Extension (CE).

A. Execute the following commands in your elevated command prompt while replacing the appropriate parameters with your own environment's values:

 gcloud iam service-accounts create "velos-gcp-ce-sa" --display-name "velos-gcp-ce-sa"


5. Assign velos_ce_role (created in step 1, above) to the velos-gcp-ce-sa service account

A. Execute the following commands in your elevated command prompt while replacing the appropriate parameters (in blue) with your own environment's values:

gcloud projects add-iam-policy-binding ProjectID --member serviceAccount:"velos-gcp-ce-sa@projectID.iam.gserviceaccount.com" --role "velos_ce_role" --no-user-output-enabled --quiet

6. Create the velos-gcp-worker-sa service account

A. Execute the following commands in your elevated command prompt while replacing the appropriate parameters with your own environment's values:

gcloud iam service-accounts create "velos-gcp-worker-sa" --display-name="velos-worker-sa"


7. Assign velos_worker_role (created in step 1, above) to the velos-gcp-worker-sa service account within the CE project

A. Execute the following commands in your elevated command prompt while replacing the appropriate parameters (in blue) with your own environment's values:

gcloud projects add-iam-policy-binding ProjectID --member serviceAccount:"velos-gcp-worker-sa@projectID.iam.gserviceaccount.com" --role "velos_worker_role" --no-user-output-enabled --quiet

Multiple Projects

For the sake of this documentation, we will refer to the following entities:

  • Organization: the entirety of the objects in this GCP account including the roles. 
  • Host Project: the entity that stores the management service accounts.
  • Cloud Extension (CE) Project: the entity that stores the cloud extension service accounts and the Velostrata Cloud Extension VM(s).
  • Destination Project: Any project that VMs are being migrated into. 

Using the entities above, the table below presents an outline of the steps you'll take and where those steps take place. At one point, you can pick either option A or option B. Pick option A if you want to assign permissions at the organization-level. This has fewer steps but less permissions granularity. Pick option B if you want to assign permissions on a per-project basis, which has more steps but has more permissions granularity and access control.

The table below is simply here to provide a visual overview of the steps you will take and is meant to be used in addition to the comprehensive steps below (not in lieu of). 




CREATE roles ASSIGN to scope



Organization [step1]
velos_mgmt_role, velos_ce_role, velos_worker_role, velos_listnetworks_role
[step 4] velos-mgmt-sa











CREATE service accounts ASSIGN roles to service accounts ASSIGN IAM Policy to service account ASSIGN to scope
PICK ONLY ONE OPTION A: organization-wide Host or CE Project
[step 2] velos-mgmt-sa [step 3] velos_mgmt_role
OPTION B: project-specific
Host Project
[step 5] Velos_MGMT_ListNetworks_Role
(Assign this role to the velos-mgmt-sa in the Host Project Context)


Each CE Project and Destination Projects


[step 6] Velos_MGMT_SA with SA_MGMT_Role


CE Project [step 7] Velos-CE-SA@CE-Project [step 8] Velos-CE-Role [step 9] velos-mgmt-sa    



Destination Project [step 10] Velos-Worker-SA@project2 [step 11] Velos-Worker-Role [step12] velos-mgmt-sa

Before proceeding, there are a number of values you'll need when modifying the upcoming commands. These commands will be represented in the instructions by being in bold italics. The commands you'll encounter are as follows:

Parameter Description GCloud CLI command to find
orgadmin@google.com the organization-level administrator N/A
organizationID the numerical ID of the organization gcloud organizations list
projectID the alphanumeric ID of the project where the velos-mgmt-sa and velos-ce-sa service accounts are created.  gcloud projects list --format="table[box,title='ProjectsIDs'](name,projectId:label=ProjectID)"
projectName the alphanumeric name of the project associated with the projectID (above). These names may or may not be the same. gcloud projects list --format="table[box,title='ProjectsIDs'](name,projectId:label=ProjectID)"
serviceProjectID the numerical ID of the service project where VMs will be migrating to gcloud projects list --format="table[box,title='ProjectsIDs'](name,projectId:label=ProjectID)"

For more information about the following glcoud commands and their parameters, please reference the Google documentation here: https://cloud.google.com/sdk/gcloud/reference.

Step-by-step Walkthrough:

1. Create the Velostrata Roles within GCP at the Organization level

A. Open an elevated command prompt so you can use the GCP SDK to run the following command while replacing the appropriate parameters (in blue) with your own environment's values:

gcloud auth login orgadmin@google.com --no-launch-browser --brief

B. Download this zip file which contains the YAML files needed to create these roles. 

C. Unzip the file and save to a directory you'll remember.

D. Execute the following commands while replacing the appropriate parameters (in blue) with your own environment's values:

gcloud iam roles create "velos_mgmt_role" --organization organizationId --file ./velos_gcp_org_mgmt_role.yaml --no-user-output-enabled --quiet

gcloud iam roles create "velos_ce_role" --organization organizationId --file ./velos_gcp_org_ce_role.yaml --no-user-output-enabled --quiet

gcloud iam roles create "velos_worker_role" --organization organizationId --file ./velos_gcp_org_worker_role.yaml --no-user-output-enabled --quiet

gcloud iam roles create "velos_listnetwork_role" --organization organizationId --file ./velos_gcp_org_listnetworks_role.yaml --no-user-output-enabled --quiet


2. Create the velos-gcp-mgmt-sa service account in GCP

Note: The velos-gcp-mgmt-sa service account can be created in any of the project you have in your setup, Velostrata recommends to create this service in the host project to simplify configuration 

A. Execute the following commands in your elevated command prompt while replacing the appropriate parameters (in blue) with your own environment's values:

gcloud config set project projectId

gcloud iam service-accounts create "velos-gcp-mgmt-sa" --display-name "Velos-gcp-mgmt-sa"

 

3. Assign velos_mgmt_role (created in step 1, above) to the velos-gcp-mgmt-sa service account

A. Execute the following commands in your elevated command prompt while replacing the appropriate parameters (in blue) with your own environment's values:

Note: ProjectID is the id of the project you used when creating velos-gcp-mgmt-sa service account in step 2.

gcloud projects add-iam-policy-binding ProjectID --member serviceAccount:"velos-gcp-mgmt-sa@projectID.iam.gserviceaccount.com" --role organizations/organizationId/roles/"velos_mgmt_role" --no-user-output-enabled --quiet

STOP: YOU HAVE REACHED A DECISION POINT!

At this point, you can pick either option A (step 4) or option B (steps 5 and 6).

Pick option A if you want to assign permissions at the organization-level. This has fewer steps but less permissions granularity. Pick option B if you want to assign permissions on a per-project basis, which has more steps but has more permissions granularity and access control. 

If you pick option A, please perform step 4 and then skip to step 7.

If you pick option B, please skip to step 5 and continue. 

OPTION A

If you proceed with option A, please skip steps 5 and 6 after you're done with step 4.

4. Assign velos-gcp-mgmt-sa at the organization-level in GCP IAM

Note: This gives the velos-gcp-mgmt-sa service account access to all projects in the organization, and prevents the GCP administrator from having to manually create this service account in every project. This action must be performed via the GCP Console by an administrator with access to the organization. 

A. Login to your GCP account as an organization-level administrator

B. Click the project selection at the top and pick your organization:

C. From the GCP menu, select IAM and click the ADD button

D. Populate the full name of your velos-gcp-mgmt-sa service account (see example below) and select the Role (Custom > Velos Mgmt Role) and click SAVE.

OPTION B:

If you completed step 4, skip steps 5 and 6. Move on to step 7. 


5. Assign velos_gcp_org_listnetworks_role to velos-gcp-mgmt-sa

The ProjectID here is the ID of the host project.

A. Execute the following commands in your elevated command prompt while replacing the appropriate parameters (in blue) with your own environment's values:

gcloud projects add-iam-policy-binding ProjectID --member serviceAccount:"velos-gcp-mgmt-sa@projectID.iam.gserviceaccount.com" --role organizations/organizationId/roles/"velos_gcp_org_listnetworks_role.yaml" --no-user-output-enabled --quiet


6. Assign velos_mgmt_role to velos-gcp-mgmt-sa:

For each Cloud Extension (CE) destination project, perform step A, below, replacing ProjectID with the appropriate CE destination project ID.

A. Execute the following commands in your elevated command prompt while replacing the appropriate parameters (in blue) with your own environment's values:

gcloud projects add-iam-policy-binding ProjectID --member serviceAccount:"velos-gcp-mgmt-sa@projectID.iam.gserviceaccount.com" --role organizations/organizationId/roles/"velos_mgmt_role" --no-user-output-enabled --quiet


7. Create the velos-gcp-ce-sa service account in GCP

You will create this account in theproject where you plan to deploy the Velostrata Cloud Extension (CE).

A. Execute the following commands in your elevated command prompt while replacing the appropriate parameters (in blue) with your own environment's values:

gcloud config set project CEProjectId

gcloud iam service-accounts create "velos-gcp-ce-sa" --display-name "velos-gcp-ce-sa"


8. Assign velos_ce_role (created in step 1, above) to the velos-gcp-ce-sa service account

A. Execute the following commands in your elevated command prompt while replacing the appropriate parameters (in blue) with your own environment's values:

gcloud projects add-iam-policy-binding CEProjectID --member serviceAccount:"velos-gcp-ce-sa@projectID.iam.gserviceaccount.com" --role organizations/organizationId/roles/"velos_ce_role" --no-user-output-enabled --quiet


9. Assign a policy that maps the velos-gcp-ce-sa service account to the velos-mgmt-sa service account

Note: this is required because the velos-gcp-mgmt-sa service account will create instances that will use the velos-gcp-ce-sa service account.

A. Navigate to the folder with the YAML files that you previously downloaded. 

B. Open the YAML file named "sa_mapping.yaml" in your preferred text editor

Note: Be careful when editing these files as they are case- and space-sensitive. 

C. Identify line 5 which will look like this:

          "serviceAccount:velos-gcp-mgmt-sa@projectID.iam.gserviceaccount.com"

D. Carefully replace "projectName" with the same value you've been using already (like in step 2, where you created the velos-gcp-mgmt-sa service account). While adding your projectName, also be sure not to remove or modify anything else, including the spaces/tabs at the beginning of this line (as that may break the YAML formatting). 

E. Save the file and exit your text editor. This file is now ready for usage in future steps.

F. Execute the following commands in your elevated command prompt while replacing the appropriate parameters (in blue) with your own environment's values:

gcloud iam service-accounts set-iam-policy "velos-gcp-ce-sa@projectID.iam.gserviceaccount.com" ./sa_mapping.yaml --no-user-output-enabled --quiet


10. Create the velos-gcp-worker-sa service account

Note: Steps 1-9 only have to be performed once. Steps 11-12, however, have to be performed for every unique destination project that you intend to migrate into. 

A. Execute the following commands in your elevated command prompt while replacing the appropriate parameters (in blue) with your own environment's values:

gcloud config set project destinationProjectId

gcloud iam service-accounts create "velos-gcp-worker-sa" --display-name="velos-gcp-worker-sa"


11. Assign velos_worker_role (created in step 1, above) to the velos-gcp-worker-sa service account

A. Execute the following commands in your elevated command prompt while replacing the appropriate parameters (in blue) with your own environment's values:

gcloud projects add-iam-policy-binding CEProjectId --member serviceAccount:"velos-gcp-worker-sa@projectId.iam.gserviceaccount.com" --role organizations/organizationId/roles/"velos_worker_role"


12. Assign a policy that maps the velos-gcp-worker-sa service account to the velos-gcp-mgmt-sa service account

Note: this is required because the velos-mgmt-sa service account will create instances with the velos-gcp-worker-sa service account.

A. Execute the following commands in your elevated command prompt while replacing the appropriate parameters (in blue) with your own environment's values:

gcloud iam service-accounts set-iam-policy "velos-gcp-worker-sa@projectID.iam.gserviceaccount.com" ./sa_mapping.yaml --no-user-output-enabled --quiet