Terraform Deployment Guide

Note: Terraform deployment options are still in preview.

Background

This guide will walk you through using Terraform to:

• Create a VPC
• Create an EKS cluster
• Create a Route53 subdomain
• Create a Cognito user pool
• Deploy Kubeflow with Cognito as an identity provider

Additional background on using Cognito with the AWS Distribution for Kubeflow can be found here.

Terraform documentation can be found here.

Prerequisites

Be sure that you have satisfied the installation prerequisites before working through this guide.

Specifially, you must:

• Create a Ubuntu environment
• Clone the repository
• Install the necessary tools

Additionally, ensure you are in the REPO_ROOT/deployments/cognito/terraform folder.

If you are in repository’s root folder, run:

cd deployments/cognito/terraform
pwd

Deployment Steps

Configure

1. Register a domain using Route 53. When you register a domain with Route 53, it automatically creates a hosted zone for the domain.

   • The provided Terraform stack will create and delegate a subdomain for the Kubeflow platform automatically.
   • If you do not use Route53 for your top level domain, you can follow the steps in create a subdomain section of load balancer guide to create a subdomain manually and provide the route 53 subdomain hosted zone name as input to the terraform stack.
     • Additionally you have to set the Terraform variable create_subdomain=false:

       export TF_VAR_create_subdomain="false"
       

2. Define the following environment variables:

   # Region to create the cluster in
   export CLUSTER_REGION=
   # Name of the cluster to create
   export CLUSTER_NAME=
   # Name of an existing Route53 root domain (e.g. example.com)
   export ROOT_DOMAIN=
   # Name of the subdomain to create (e.g. platform.example.com)
   export SUBDOMAIN=
   # Name of the cognito user pool to create
   export USER_POOL_NAME=
   

3. Save the variables to a .tfvars file:

   cat <<EOF > sample.auto.tfvars
   cluster_name="${CLUSTER_NAME}"
   cluster_region="${CLUSTER_REGION}"
   aws_route53_root_zone_name="${ROOT_DOMAIN}"
   aws_route53_subdomain_zone_name="${SUBDOMAIN}"
   cognito_user_pool_name="${USER_POOL_NAME}"
   EOF
   

All Configurations

A full list of inputs for the terraform stack can be found here.

Preview

View a preview of the configuration you are about apply:

terraform init && terraform plan

Apply

Run the following command:

make deploy

Connect to your Kubeflow dashboard

1. Head over to your user pool in the Cognito console and create a user with email user@example.com in Users and groups.
2. Get the link to the central dashboard:

   terraform output -raw kubelow_platform_domain
   

3. Open the link in the browser and connect via the user credentials that were just configured.

Cleanup

Uninstall Kubeflow on AWS with a single command.

make delete