Appendix: Creating GCP Roles and Service Accounts (manually)

Before you proceed

Please read this first:

If you have already completed your service account creation via scripts (as detailed in this article) then you should skip this article entirely. 

The instructions in this section are mostly for educational purposes and they are labor-heavy, and we highly recommend using the scripts as detailed in this section instead to accomplish service account creation within migration projects. 

Instructions

Standalone Project

Looking to save some time? Try this section with scripts to perform these operations for you instead.

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

Looking to save some time? Try this section with scripts to perform these operations for you instead.

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. 

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:

Note: After step 3, you will pick between two options regarding how you assign security privileges. You will select 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.

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


INSTRUCTIONS RESUME HERE AFTER PERFORMING OPTION A (step 4) or OPTION B (steps 5 & 6):

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