Skip to main content

Terraform deployment quickstart

· 10 min read
Bill Kable
Bill Kable
Engineer

Hi all, we are happy to announce we are now sharing the Educates Terraform Modules project that provides support for deploying Educates on Amazon and Google Cloud providers.

Its release versions are independent from the Educates Training Platform releases; however, it is currently tested and verified to work on Educates 3.2.x and 3.3.x on Kubernetes version 1.32.

We've provided the quick start here so you can experiment with it and give feedback.

Why?​

If you read the Installing Educates on a cloud provider article and/or watched the accompanying video, you would notice that Educates requires a preliminary setup of a Kubernetes cluster before you can install Educates.

You could install Kubernetes (K8s) yourself, especially if are a Certified Kubernetes Administrator (CKA). But really it is more convenient to automate the K8s cluster provisioning as much as possible.

We selected Terraform given its widespread use in DevOps and Platform Engineering domains.

What is provided and supported?​

The Educates Terraform Modules project include several modules:

  1. Infrastructure modules: deploy K8s cluster

  2. Platform

    • Educates: Deploy Educates Ingress related prerequisites, Lookup Service, and Educates Training Platform

  3. Root Modules: Reference implementations for installing Educates using Infrastructure and Platform modules

The Educates Terraform Module project is released independently from the Educates Training Platform; however, is currently tested and verified to work on Educates 3.2.x and 3.3.x.

You can see the project releases here.

note

Consider the Root Modules reference implementation only. You should build your own using the infrastructure and platform modules, using the reference implementations as inspiration.

We'll discuss limitations later in this article.

Quick start​

Getting started is easy.

In this example, we'll walk through deploying Educates on GKE using Terraform, from your development workstation.

You'll need some set up first.

What you should know before running it?​

We expect that you have a basic understanding of the following:

  • Kubernetes (K8s)

  • Your Cloud Provider (Amazon or Google): You should understand how to manage network, compute, storage, IAM users, policies and roles, K8s, and basic billing concepts

  • Terraform

  • Educates installation process - we recommend you have already reviewed the following:

How much will running this cost?​

If you've followed the instructions in the Configure Terraform variables section, and use the main.tfvars.example template, your cluster and compute costs will be low.

You should be able to setup, test, and tear down your Educates cluster within a 24 hour period, and stay within a $5-10 USD range.

Prerequisites​

You'll need the following before you start:

  1. Amazon or Google Cloud IAM account: With sufficient privileges to create/update/delete (for this example we use Google):

    • VPC/Network resources
    • K8s cluster
    • Compute and Storage
    • DNS Zones

  2. Educates Cluster Ingress DNS Zone configuration: You'll need DNS configuration for your Educates cluster. You can read more about configuring that:

  3. Developer workstation:

    • Mac OSX
    • Linux distribution
    • Windows Subsystem for Linux (WSL)

  4. Cloud provider CLI: For this example, install and use gcloud. You will also need to authenticate via an IAMS per #1 interactively, and also for the sdk:

    gcloud auth login
    ... # auth interactively
    gcloud auth application-default login
    ... # auth interactively

  5. Terraform CLI: You can install or manage specific versions of terraform with tfenv.

    The following installs, sets and verifies the version of terraform we are using in the quick start:

    tfenv install 1.12.1
    tfenv use 1.12.1
    terraform version

    You should see Terraform version successfully installed:

    Terraform v1.12.1
    on {platform}

  6. kubectl: We'll need access to the cluster after deployment.

  7. Educates CLI: We'll need to deploy/manage a workshop to verify the cluster by either method:

Root Module Reference implementations​

We'll use the GKE reference implementation Terraform plan here. You can read how to run it here.

Alternatively, you could use the one for Amazon Elastic Kubernetes Service (EKS) here.

To prepare for running the quick start, do the following:

  1. Open a bash or zsh terminal.

  2. Set up a project directory of your choice on your developer workstation, and change your current directory to it.

    For example:

    mkdir ~/workspace
    cd ~/workspace

  3. Fork/clone the Educates Terraform modules repo:

    git clone https://github.com/educates/educates-terraform-modules.git

  4. Change your working directory to the GKE root module directory (from where we will run the terraform plan):

    cd educates-terraform-modules/root-modules/educates-on-gke

Configure Terraform variables​

Review the Configuration examples.

For this example, we'll use the main.tfvars.example as a template from which to build the main.tfvars.

  1. Copy the example template to main.tfvars file:

    cp ./examples/main.tfvars.example ./main.tfvars

  2. Configure the placeholder variables in the main.tfvars file:

    • gcp_project_id: your Google Cloud project id where you will deploy the cluster
    • gcp_region: Google Cloud region where you will deploy the cluster
    • cluster_name: Pick a name for your cluster (should be between 6-12 characters)
    • educates_ingress_domain: the domain associated with the DNS zone configured for your Educates cluster

  3. Notice the deploy_educates configuration flag. By default, the root modules assume you want to deploy Educates using the Educates Platform module. It uses the Carvel Kapp Controller for reconciliation of Educates components into the cluster.

    If you prefer to install Educates via the CLI as in Installing Educates on a cloud provider article, set the deploy_educates flag to false. The Educates module will not be deployed.

Prepare and run the plan to deploy cluster​

  1. Initialize terraform in your development workspace:

    terraform init

    You can see a similar output:

  2. Run the plan (this step is optional, but useful if you need to cache the plan in a CI/CD workflow):

    terraform plan -var-file ./main.tfvars

    You can see a similar output:

  3. Apply the plan:

    terraform apply -var-file ./main.tfvars

    Depending on your network connection speed/bandwidth, as well as Google's resource constraints, the plan may take 15-20 minutes to apply.

    You can see a similar output:

warning

Note that when running terraform cli commands, you will be caching state of the plan in the working directory on your workstation into the following directories/files:

  • .terraform
  • .terraform.lock.hcl
  • terraform.state
  • terraform.state.backup

State of the terraform plan and the associated cluster deployment workflow is not automatically saved elsewhere, so if you were to modify or delete these resources, you would not be able to update or destroy your cluster using Terraform.

This is one of the reasons these are just example reference implementations, and it's up to you to know what you're doing. You should use the released modules in your own plans, taking inspiration from these reference implementations, but guaranteeing to properly save the state of your plan executions.

Setup K8s access​

The terraform plan will generate a kubeconfig file for you, with a naming pattern of kubeconfig-${cluster_name}-token.yaml. We'll verify K8s access here:

  1. Set KUBECONFIG to point to it in your terminal session:

    export KUBECONFIG=./kubeconfig-YOUR_CLUSTER_NAME-token.yaml

  2. Verify you can access cluster pods using your existing Google Cloud IAM session and provided kubeconfig access:

    kubectl get pods -A

You can see a similar output:

Deploy a workshop and verify​

You can verify the platform installation per the Installing Educates on a cloud provider (Part 2 - Verification) article

Tear down cluster​

When you are done with the cluster, tear it down as follows:

terraform destroy -var-file ./main.tfvars

Given we are not using -auto-approve, you will be prompted to review the plan.

Confirm with "yes".

You can see a similar output:

warning

If you removed your terraform state files, you will not be able to run the terraform destroy command.

You would need to clean up your cluster resources manually in the following order:

  • Educates portals and lookup service configuration resources
  • Educates deployment
  • Node pools
  • GKE cluster
  • Volumes
  • VPC resources
  • Custom policies/roles

Limitations​

Note the following limitations of the provided Educates Terraform root modules:

  1. Terraform state is not handled explicitly - it relies on the user to handle externally.
  2. Continuous integration or continuous delivery pipelines are currently not supported.
  3. They have not yet been tested in either commercial, enterprise, or large scale implementations.
  4. They are currently considered reference implementation only.
  5. Currently only Amazon EKS and Google GKE providers are supported.

We encourage you to give feedback through issues or pull requests so we can improve the deployment automation experience.

Conclusion​

In this article, we walked through provisioning Educates using Terraform on Google Cloud.

If you are an Amazon user, we encourage you to walk through the EKS root module provisioning.

Hopefully we've shown you the value of using Terraform to streamline your Educates deployment workflow.