Google Cloud Platform preparations

Quetzal can be deployed as a Kubernetes application on Google Cloud Platform (GCP). To achieve this, follow this guide.

Project

  1. Create a project on the GCP console by selecting New project .

    When you create a GCP project, you will give it a unique name, its project id. In this guide, this identifier will be referred as <your-project-id>.

  2. After creating the project, head to the IAM & admin menu to see the list of members of the project.

    Make sure that your email address is listed as a project owner.

  3. Download and install gcloud.

    Most of the operations described in this guide can be done through the GCP console, a very rich web-based application to manage your cloud resources and services. However, this guide will do all operations on the command-line interface using gcloud, because it is easier to describe.

  4. Once you have installed gcloud, authenticate with the email address listed in step 2.

    $ gcloud auth login
    # ... a browser window will appear to login ...
    
  5. Configure the default settings of the project.

    $ gcloud config set project <your-project-id>
    $ gcloud config set compute/zone europe-west1-c # or some other region
    
  1. Verify your configuration.

    $ gcloud config list
    [compute]
    region = europe-west1
    zone = europe-west1-c
    [core]
    account = your.email@example.com    # << verify that this is your email...
    disable_usage_reporting = True
    project = <your-project-id>         # << ... and that this is your GCP project
    
    Your active configuration is: [default]
    

Credentials

Quetzal uses and manages several GCP resources through the GCP JSON API. This access is subject to the permissions defined by the Identity and Access Management (IAM) component of GCP. You need to create a service account for Quetzal and associate a list of permissions to it. In other words, you need to setup some credentials. The following steps explain how to create these credentials.

  1. Create a service account. Note the email entry, which will be used later.

    $ gcloud iam service-accounts create quetzal-service-account \
        --display-name="Quetzal application service account" \
        --format json
    Created service account [quetzal-service-account].
    {
      "displayName": "Quetzal application service account",
      "email": "quetzal-service-account@<your-project-id>.iam.gserviceaccount.com",
      ...
    }
    
  2. Create a credentials key JSON file for the service account.

    In the following code example, it is saved as conf/credentials.json.

    $ gcloud iam service-accounts keys create \
       conf/credentials.json \
       --iam-account=quetzal-service-account@<your-project-id>.iam.gserviceaccount.com
    

    Important

    Anyone with this file could use your GCP resources, so this file should not be shared or committed to your version control system.

    Keep it secret, keep it safe.

  3. Create an IAM role.

    We need to create a role that encapsulates all the permissions needed by the Quetzal application. These permissions are listed on the gcp_role.yaml file.

    $ gcloud iam roles create quetzal_app_role \
      --project <your-project-id> \
      --file gcp_role.yaml
    
  4. Associate the service account to the IAM role.

    Finally, the service account created before needs to be associated with the permissions defined in the IAM role.

    $ gcloud projects add-iam-policy-binding <your-project-id> \
      --member=serviceAccount:quetzal-service-account@<your-project-id>.iam.gserviceaccount.com \
      --role=projects/<your-project-id>/roles/quetzal_app_role
    

APIs

Quetzal uses several GCP services through their APIs. You need the enable the following APIs on GCP API library:

  • Cloud Storage, used to store all files in Quetzal.

  • Kubernetes Engine API, used to create a Kubernetes cluster that hosts the Quetzal services.

Docker & Kubernetes

Quetzal uses Docker images and the Google Container Registry (GCR).

  1. Install Docker. Make sure you are able to create Docker images by following the test Docker installation instructions.

  2. Use gcloud to configure a Docker registry. This will enable Docker to push images to GCR.

    $ gcloud auth configure-docker
    
  3. Finally, install the kubernetes client:

    $ gcloud components install kubectl
    

IP address reservation

This step is optional. When deploying Quetzal, you might want to associate it to some fixed IP address (in order to associate it in your DNS records). You can reserve one IP as follows (change the region to your case):

$ gcloud compute addresses create quetzal-stage-server-ip \
 --description="Quetzal stage server external IP" \
 --region=europe-west1 \
 --network-tier=PREMIUM

Get the reserved IP with the following command:

$ gcloud compute addresses list
NAME                     ADDRESS/RANGE   TYPE  PURPOSE  NETWORK  REGION        SUBNET  STATUS
quetzal-stage-server-ip  x.x.x.x                                 europe-west1          RESERVED

Important

GCP reserved IPs incur in charges if they are not associated to a service. If you are not going to use it immediately, you may want to do this as late as possible.