Links

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.

Before you begin

You must have already built a track 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 track 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. 1.
    Add an Instruqt Cloud Client container to your track.
  2. 2.
    Add a GCP project to your track.
  3. 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 track

🌐 Web UI
💻 Instruqt CLI
  1. 1.
    Open your browser and go to play.instruqt.com. ↳ Instruqt shows your content.
  2. 2.
    Click the TRACK_NAME of the track where you want to add GCP project access. ↳ Instruqt shows the corresponding Track overview page.
  3. 3.
    Click Track details followed by Sandbox to open the Sandbox page.
  4. 4.
    Click Add container +. ↳ The Create container page opens.
  5. 5.
    Enter/select these values:
    Field
    Value
    Name
    cloud-client
    Image
    gcr.io/instruqt/cloud-client
    Ports
    80
    Shell
    /bin/bash
  6. 6.
    Click Save to add the container. ↳ On the Sandbox page, you will see the new container.
  1. 1.
    Open the file config.yml in your code editor.
  2. 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 track

🌐 Web UI
💻 Instruqt CLI
  1. 1.
    Click Add Google Cloud project + on the Sandbox page. ↳ The Create Google Cloud project page opens.
  2. 2.
    In the Name field, enter gcpproject.
    Optional services
    Note the Services field where you can enable the different Google Cloud APIs. Read the IAM permissions section to learn more about how to enable the right services for your learners.
  3. 3.
    Click Save to add the GCP project. ↳ On the Sandbox page, you will see the new GCP project.
  4. 4.
    Click Back to return to the Track overview page.
  1. 1.
    Copy and paste the following code into config.yml:
    gcp_projects:
    - name: gcpproject
    services: []
    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: []
    roles: []
    Optional services
    Note the services property under gcp_projets. This is where you can enable the different Google Cloud APIs and the required Google Cloud IAM roles for the User and Service accounts. Read the IAM permissions section to learn more about how to enable the right services for your learners.

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

🌐 Web UI
💻 Instruqt CLI
  1. 1.
    Click Add Challenge on the Track overview page. ↳ The New challenge page opens.
  2. 2.
    Enter/select these values:
    Field
    Value
    Title
    GCP project
    Slug
    gcp-project
    Assignment > Editor tab
    Markdown text of your liking
    Teaser
    Learn to work with a GCP project
  3. 3.
    Click Save to add the challenge. ↳ On the Track overview page, you will see the new challenge.
  4. 4.
    Click Edit on the new challenge.
  5. 5.
    Click Tabs followed by New tab. ↳ The New tab page opens.
  6. 6.
    Enter/select these values to set the GCP console:
    Field
    Value
    Title
    CGP project console
    Type
    Service
    Host
    cloud-client
    Path
    /
    Port
    80
  7. 7.
    Click Save to add the tab.
  8. 8.
    Click New tab again.
  9. 9.
    Enter/select these values to set the gcloud CLI:
    Field
    Value
    Title
    gcloud CLI
    Type
    Terminal
    Host
    cloud-client
  10. 10.
    Click Save to add the tab. ↳ On the Challenge tabs page, you will see the new tabs.
  11. 11.
    Click Back followed by Build track.
  12. 12.
    Click Start track and test your GCP project track.
  1. 1.
    Open a terminal and move to your track directory.
  2. 2.
    Enter the following command to create a new challenge:
    instruqt challenge create --title "GCPproject"
    ↳ Instruqt CLI created a directory for the challenge. And an assignment.md file inside the challenge directory.
  3. 3.
    Open the assignment.md file in your code editor.
  4. 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
    ---
    ⇨ You can add the assignment text of your liking in Markdown after line 17.
  5. 5.
    Save file assignment.md.
  6. 6.
    Push the track to the Instruqt platform:
    instruqt track push
  7. 7.
    Play and test the track:
    instruqt track open
    ↳ Your browser opens, showing the Track overview page. Click Start track to play the track.

Using 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 user that has access to the project
INSTRUQT_GCP_PROJECT_${NAME}_USER_PASSWORD
This injects the password of the user
INSTRUQT_GCP_PROJECT_${NAME}_SERVICE_ACCOUNT_EMAIL
This injects the email address of the services account for this project
INSTRUQT_GCP_PROJECT_${NAME}_SERVICE_ACCOUNT_KEY
This injects the Base64 encoded key for the services account

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. 1.
    Start your GCP project track and start the first challenge.
  2. 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
💻 Instruqt CLI
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.
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: