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](../images/vpcgen2cluster.png)
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.4" ], "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.4", "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
, runibmcloud 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.