GCP projects

Give learners access to GCP projects.

This guide explains how to access a Google Cloud Platform (GCP) project from Instruqt.

A GCP project is a set of configuration settings that define how your app interacts with Google services and what resources it uses.

— Google Cloud Platform project documentation

Before you begin

You must have already created a track or sandbox preset to which you can add access to a GCP project.

Access GCP projects

It is best to add the Instruqt Cloud Client container to your sandbox to give a learner access to a GCP project. Because the Instruqt Cloud Client container:

• Exposes links to GCP Cloud Consoles for the resources configured in the config.yml file, with the credentials required to log in.

• Includes the gcloud CLI, pre-configured with the required credentials.

The GCP Cloud Console and the gcloud CLI make it easy for content developers and learners to access Google Cloud resources from the sandbox.

It takes the following steps to give learners access to a GCP project:

1. Add an Instruqt Cloud Client container to your sandbox

2. Add a GCP project to your sandbox.

3. Add tabs to your challenges where you want to expose the GCP console or gcloud CLI.

Additionally, you can use:

• A set of environment variables that are available in the gcloud CLI.

• Google Cloud APIs that you set through IAM permissions.

Step 1: Add an Instruqt Cloud Client container to your sandbox

🌐 Web UI

1. Click the track you want to add a GCP project to. ↳ Instruqt shows the corresponding Track dashboard page.

2. In the Sandbox section, click Edit.

3. Click + Add a host. ↳ The Add host pop-up opens.

4. Pick the Container host type.

5. Enter/select these values:

   Field	Value
   Hostname	cloud-client
   Image type	Choose your own
   Container image	gcr.io/instruqt/cloud-client

6. Click Show optional settings. Enter these values:

   Field	Value
   Ports	80
   Shell	/bin/bash

7. Click Save host to add the container.

💻 Instruqt CLI

1. Open the file config.yml in your code editor.

2. Copy and paste the following code under the containers property:

   - name: cloud-client
     image: gcr.io/instruqt/cloud-client
     ports: [80]
     shell: /bin/bash

Step 2: Add a GCP project to your sandbox

🌐 Web UI

1. Click + Add a cloud account on the Sandbox page. ↳ The Add cloud account pop-up opens.

2. Select the Google provider.

3. In the Name field, enter example-project.

4. In the Services field, select the services that are going to be enabled.

5. In the Regions field, select the regions that are going to be enabled.

6. In the User Roles field, enter the desired roles for the end user.

7. In the Admin Roles field, enter the desired roles for the admin user.

8. Click Save to add the GCP project.

9. Click Back to track to return to the Track dashboard page.

💻 Instruqt CLI

1. Copy and paste the following code into config.yml:

   gcp_projects:
   - name: gcpproject
     services: []
     regions: []
     roles: []

   ↳ Your config.yml file should be similar to this now:

   version: "3"
   containers:
   - name: cloud-client
     image: gcr.io/instruqt/cloud-client
     ports: [80]
     shell: /bin/bash
   gcp_projects:
   - name: gcpproject
     services: []
     regions: []
     roles: []  

You have control over which services and regions learners can access. We highly recommend you only provide access to what is strictly needed to complete the track. See IAM permissions for more detail.

Only enabled services and regions configured by the team administrator can be selected and/or specified. See more details in Cloud services and regions

When specifying Admin Roles, an additional admin user and a service account will be created with the designated roles.

For setting up the cloud account in lifecycle scripts, it is recommended to use an admin user with elevated privileges. This ensures the ability to perform operations requiring higher privileges than those assigned to the end user.

Note: Admin credentials are injected exclusively into lifecycle scripts, unlike end user credentials which are exposed as environment variables on virtual machines and containers.

Step 3: Add tabs to expose the GCP console and gcloud CLI

🌐 Web UI

1. In the Challenges section, click Add new, and select Assignment from the dropdown.

2. On the new challenge page, input these values:

   Field	Value
   Name	GCP project
   URL	gcp-project
   Description	Learn to work with a GCP project

3. Click Save.

4. Click Tabs followed by Add new tab.

5. Select the Your applications tab type.

6. Input these values to set the GCP console:

   Field	Value
   Tab name	CGP project console
   Select your host	cloud-client
   Path	/
   Port	80

7. Click Save to add the tab.

8. Click Add new tab again.

9. Select the Terminal tab type.

10. Input these values to set the gcloud CLI:

    Field	Value
    Tab name	gcloud CLI
    Host	cloud-client

11. Click Save to add the tab.

12. Click Back to track.

13. Click Play track and test your GCP project track.

💻 Instruqt CLI

1. Open a terminal and change to your track directory.

2. Enter the following command to create a new challenge:

   instruqt challenge create --title "GCPproject"

3. Open the assignment.md file in your code editor.

4. Copy and paste the following code into assignment.md to set the GCP console and gcloud CLI:

   ---
   slug: gcp-challenge
   type: challenge
   title: GCP project
   teaser: Learn to work with a GCP project
   tabs:
   - title: GCP Console
     type: service
     hostname: cloud-client
     path: /
     port: 80
   - title: gcloud CLI
     type: terminal
     hostname: cloud-client
   difficulty: basic
   timelimit: 600
   ---
   
   Example assignment!

5. Save file assignment.md.

6. Push the track to the Instruqt platform:

   instruqt track push

7. Play and test the track:

   instruqt track open

   ↳ Your browser opens, showing the Track overview page, select Play.

Environment variables

Adding a GCP project to your track also sets a list of environment variables that you can use in commands and scripts:

Environment variable	Description
INSTRUQT_GCP_PROJECTS	A comma-separated list of project names that can be used to fill ${NAME} in the variables below
INSTRUQT_GCP_PROJECT_${NAME}_PROJECT_NAME	This injects the project display name
INSTRUQT_GCP_PROJECT_${NAME}_PROJECT_ID	This injects the project ID
INSTRUQT_GCP_PROJECT_${NAME}_USER_EMAIL	This injects the email address of the end user that has access to the project
INSTRUQT_GCP_PROJECT_${NAME}_USER_PASSWORD	This injects the password of the end user
INSTRUQT_GCP_PROJECT_${NAME}_SERVICE_ACCOUNT_EMAIL	This injects the email address of the end user services account for this project
INSTRUQT_GCP_PROJECT_${NAME}_SERVICE_ACCOUNT_KEY	This injects the Base64 encoded key for the end user services account
INSTRUQT_GCP_PROJECT_${NAME}_ADMIN_USER_EMAIL	This injects the email address of the admin user (Admin credentials are only injected into lifecycle scripts)
INSTRUQT_GCP_PROJECT_${NAME}_ADMIN_USER_PASSWORD	This injects the password of the admin user (Admin credentials are only injected into lifecycle scripts)
INSTRUQT_GCP_PROJECT_${NAME}_ADMIN_SERVICE_ACCOUNT_EMAIL	This injects the email address of the admin services account (Admin credentials are only injected into lifecycle scripts)
INSTRUQT_GCP_PROJECT_${NAME}_ADMIN_SERVICE_ACCOUNT_EMAIL	This injects the Base64 encoded key for the admin services account (Admin credentials are only injected into lifecycle scripts)

Example

This example shows the id of the GCP project from a terminal by using two environment variables. The value of the INSTRUQT_GCP_PROJECTS environment variable is inserted in the INSTRUQT_GCP_PROJECT_${NAME}_PROJECT_ID environment variable.

To follow along:

1. Start your GCP project track and start the first challenge.

2. Move over to the Cloud CLI terminal and enter the following command:

   eval echo "\${INSTRUQT_GCP_PROJECT_${INSTRUQT_GCP_PROJECTS}_PROJECT_ID}"

   ↳ The terminal shows the id of your GCP project.

Setting IAM permissions

The services list allows you to specify which Google Cloud APIs should be accessible in the sandbox. See Google Cloud APIs for more information. The roles list allows you to specify which Google Cloud IAM roles should be granted to the projects Service and User account. A full list of all the Google Cloud IAM roles can be found here Understanding Roles.

Only enable a service if it is required for your track to function. You can test this by removing the service and checking whether the track still works.

Examples

Add virtual machines (outside of the standard sandbox virtual machines)

You should add compute.googleapis.com to the services list and roles/compute.admin to the roles list if your track requires virtual machines outside of the standard sandbox virtual machines.

Add a Google Kubernetes Engine (GKE) cluster

If your track needs a GKE cluster, you will also want to add the Kubernetes Engine API container.googleapis.com to the services list and roles/container.admin to the roles list.

To set these services:

🌐 Web UI

To add virtual machines to your GCP project, enter the following in the Services field:

compute.googleapis.com

And click Add.

Then enter the following in the Roles field:

roles/compute.admin

And click Add. To add a GKE cluster to your GCP project, enter the following in the Assigned Roles field:

container.googleapis.com

And click Add.

Then enter the following in the Roles field:

roles/container.admin

And click Add.

💻 Instruqt CLI

To add both virtual machines and a GKE cluster to your GCP project, edit your config.yml file to include this content:

gcp_projects:
- name: gcpproject
  services:
  - compute.googleapis.com
  - container.googleapis.com
  roles:
  - roles/compute.admin
  - roles/container.admin

Nice job! Your learners can now access GCP projects. But there is more. You can also give them access to:

• AWS accounts

• Azure subscriptions