Creating an IBM Cloud Kubernetes Service cluster on VPC infrastructure

Use one of the IBM® provided templates to create an IBM Cloud® Kubernetes Service cluster in a Virtual Private Cloud (VPC). Then, you bind the cluster to an IBM Cloud® Object Storage service instance.

Description

In this tutorial, you use the IBM® provided vpc-gen2-cluster Terraform template to create a Virtual Private Cloud (VPC) and to provision an IBM Cloud Kubernetes Service cluster on Virtual Servers for VPC. Then, you add the service credentials of an IBM Cloud Object Storage service instance as a Kubernetes secret in your cluster. You can change the default values in this template to spread your cluster across multiple subnets and zones. However, the steps in this tutorial use the default values that are provided in the template.

The following image shows the cloud architecture components that you provision as part of this tutorial.

Provisioning Terraform templates by using IBM Cloud Schematics

Cloud architecture components
Component	Description
`Region`	Region increases the availability of cluster's master node and its nodes by replicating across multiple zones of a region.
`VPC`	VPC provides you the security of a private cloud environment with the dynamic scalability of a public cloud.
`zones`	You must have one VPC subnet for each zone in your cluster. The available zones depend on the metro location that you created in the VPC.
`subnet`	VPC subnets is used to provide private IP addresses for your worker nodes and load balancer services in your cluster. You cannot change the number of IP addresses that a VPC subnet has.
`master node`	Controls and manages a set of worker nodes (workloads runtime) and resembles a cluster in Kubernetes.
`cluster`	A cluster contains a control plane and one or more compute machines, or nodes. Nodes run the applications and workloads.
`worker node`	Add the zone to your worker pool. When you add a zone to a worker pool, the worker nodes that are defined in your worker pool are provisioned in the zone and considered for future workload scheduling.

You can add worker nodes and pool to your VPC cluster by using a ibm_container_vpc_worker_pool provider resource.

The costs are incurred based on your resource usage. For more information about the VPC pricing, see VPC pricing.

Objectives

In this tutorial, you can perform the following.

Learn how to use an IBM-provided Terraform template to create a Virtual Private Cloud (VPC) and provision an IBM Cloud Kubernetes Service cluster that runs on Virtual Servers for VPC.
Create an IBM Cloud Object Storage service instance and bind the service to your IBM Cloud Kubernetes Service cluster.
Explore how to create an IBM Cloud Schematics workspace.
Create a Terraform execution plan and apply your Terraform template in IBM Cloud.
Review the IBM Cloud® resources that you create.

Time required

1 hour

Audience

This tutorial is intended for developers and system administrators who want to learn how to use Terraform templates to create and manage cloud infrastructure services by using IBM Cloud Schematics.

Prerequisites

Before you begin, complete the following prerequisites.

Create the IBM Cloud Pay-As-You-Go or Subscription IBM Cloud account.
Install the IBM Cloud CLI and the Schematics CLI plug-in.
Make sure you set environment variables for IBMCLOUD_API_KEY.
Make sure that you are assigned the Manager service access role in Cloud Identity and Access Management for Schematics to create and work with a Schematics workspace.
Make sure that you are assigned the required permissions to create VPC infrastructure resources.
Follow the steps to get the required permissions to create an IBM Cloud Kubernetes Service cluster and to prepare your account for your cluster setup.
Make sure that you have the required permissions to create an instance of IBM® Key Protect and IBM Cloud Object Storage.

Creating your Schematics workspace

Use the IBM-provided Terraform template to create and configure your Schematics workspace.

Review the IBM-provided template to create an IBM Cloud Kubernetes Service cluster on VPC infrastructure.
- main.tf: This file includes the Terraform code that you run in Schematics. Your Terraform code includes data sources and resources to create a VPC with subnets in two different zones, create an IBM Cloud Kubernetes Service cluster, and configure the cluster to bind an IBM Cloud Object Storage service instance.
- output.tf: This file includes the content that you want to return after Schematics applied your Terraform template. In this case, you get the file path on your local machine where the cluster configuration and certificates are stored. You use these files to access your cluster later.
- variables.tf: This file includes all the variables that you need to specify to run your Terraform template. You can use the default values that are provided, or override them when you create the Schematics workspace.
- versions.tf: This file includes the Terraform version that this template requires.
Create a JSON file where you store the configuration of your Schematics workspace.

Creating your IBM Cloud Schematics workspace

Specify your Schematics workspaces setting by copying the following workspace JSON file and saving it as cluster_payload.json on your local machine. For more information about the payload parameters, see Schematics workspaces new command.

Example of the cluster_payload.json:

{
    "name": "mytest1_cluster",
    "type": [
        "terraform_v1.0"
    ],
    "description": "",
    "template_repo": {
      "url":"https://github.com/IBM-Cloud/terraform-provider-ibm/tree/master/examples/ibm-cluster/vpc-gen2-cluster"
    },
    "template_data": [
        {
        "folder": ".",
        "type": "terraform_v1.0",
        "variablestore": [
        {
          "name": "worker_pool_name",
          "value": "workerpool",
          "type": "string"
        },
        {
          "name": "service_instance_name",
          "value": "myservice",
          "type": "string"
        },
        {
          "name": "flavor",
          "value": "cx2.2x4",
          "type": "string"
        },
        {
          "name": "cluster_name",
          "value": "cluster",
          "type": "string"
        },
        {
          "name": "region",
          "value": "us-south",
          "type": "string"
        },
        {
          "name": "worker_count",
          "value": "1",
          "type": "string"
        },
        {
          "name": "resource_group",
          "value": "Default",
          "type": "string"
        }
        ]
    }
    ],
    "githubtoken": "<provide your githubtoken>"
}

You can edit the payload values for the variable as stated in the table:

Payload details
Variable	Value
`name`	Specify your unique name.
`type`	Terraform v1.0
`githubtoken`	Specify your GitHub token.
`variablestore`	Specify the resource group and its details. Enter the input variable such as name, type, and value that you declared in Terraform configuration file. For more information about variable store, see Variable store parameter.

Create the workspace by using the JSON file from command-line interface.

ibmcloud schematics workspace new --file <fully qualified path of cluster_payload.JSON file>

For more information about workspace creation, see command-line commands and syntax.

Sample example output

Creation Time   Mon Feb 15 19:18:55
Description
Frozen          false
ID              mytest1_cluster-62183a6b-fbed-43
Name            mytest1_cluster
Status          DRAFT

Template Variables for: examples-d3d10ae5-76ef-47
Name                    Value
worker_pool_name        workerpool
service_instance_name   myservice
flavor                  cx2.2x4
cluster_name            cluster
region                  us-south
worker_count            1
resource_group          Default

OK

You can also view the new workspace mytest1_cluster in IBM Cloud dashboard.

Verify that your workspace is created by using list command.

ibmcloud schematics workspace list

Sample example output

Name               ID                              Description     Status      Frozen
mytest1_cluster  mytest1_cluster-62183a6b-fbed-43                  ACTIVE       False

OK

Planning and applying the Terraform template

Create a Schematics execution plan. The execution plan shows the IBM Cloud resources that must be added, modified, or removed to achieve the state that is described in your Terraform template.

Your workspace must be in an Active state to perform a Schematics plan action. For more information about the workspace state, see workspace states.

During the creation of the Terraform execution plan, you are not allowed to make any changes to your workspace.

Execute the Schematics plan command. This command prompts for kube_version, run ibmcloud ks versions command to list the supported Kubernetes version to provision. The plan command gives back an activity ID.
```
ibmcloud schematics plan --id mytest1_cluster-62183a6b-fbed-43
```
Sample example output
```
Activity ID 3886e3752a0a83b04732b6666533b464

OK
```
The activity ID is used to retrieve the logs of the execution plan.
Review the execution plan to view the IBM Cloud resources. To retrieve the logs with the activity ID use the generated activity ID from step 1.
```
ibmcloud schematics logs --id mytest1_cluster-62183a6b-fbed-4
```
You can view the output from your working directory, or from the IBM Cloud dashboard to view the workspace status.
Apply your Terraform template in IBM Cloud. When you apply your Terraform template, all the IBM Cloud resources that are specified in the template are created in your IBM Cloud account.

This process takes a minute to complete. During this process, you cannot make any changes to your workspace.
```
ibmcloud schematics apply --id <workspace_ID>
```
Sample example output
```
Do you really want to perform this action? [y/N]> y

Activity ID 5676e3752a0a84565667666533b4345

OK
```
Review the logs of your workspace. See step 2 to view the logs with the workspace ID or activity ID.
Verify that the IBM Cloud resources are successfully created in your IBM Cloud.
```
ibmcloud schematics workspace get --id <WORKSPACE_ID>
```
Alternatively, through the IBM Cloud dashboard, you can view the status of the workspace. From the IBM Cloud, select Navigation Menu -> Schematics -> workspaces -> Resources to observe the apply state of the resources in your workspace.
Command to view the logs, and analyze the state of the workspace and resources creation.
```
ibmcloud schematics logs --id mytest1_cluster-62183a6b-fbed-43
```
You can view the output from your working directory, or from the IBM Cloud dashboard workspace jobs status.

What's next?

Great job! You successfully provisioned a VPC cluster by using IBM Cloud Schematics. You can now learn how to configure the cluster parameters to attach the key management services and load balancer. For more information about key management services and IBM Cloud Kubernetes worker pool, see Key Management services and IBM Cloud Kubernetes worker pool.