cluster-create.md

copyright	lastupdated	keywords	subcollection
years 2014, 2023	2023-01-30	kubernetes, clusters, worker nodes, worker pools	containers

{{site.data.keyword.attribute-definition-list}}

Preparing to create clusters

{: #clusters}

Create a cluster in {{site.data.keyword.containerlong}}. {: shortdesc}

After getting started, you might want to create a cluster that is customized to your use case and different public and private cloud environments. Consider the following steps to create the correct cluster each time.

1. Prepare your account to create clusters. This step includes creating a billable account, setting up an API key with infrastructure permissions, making sure that you have Administrator access in {{site.data.keyword.cloud_notm}} IAM, planning resource groups, and setting up account networking.
2. Decide on your cluster setup. This step includes planning cluster network and HA setup, estimating costs, and if applicable, allowing network traffic through a firewall.
3. Create your VPC Gen2 or classic cluster by following the steps in the {{site.data.keyword.cloud_notm}} console or CLI.

Preparing to create clusters at the account level

{: #cluster_prepare}

Prepare your {{site.data.keyword.cloud_notm}} account for {{site.data.keyword.containerlong_notm}}. After the account administrator makes these preparations, you might not need to change them each time that you create a cluster. However, each time that you create a cluster, you still want to verify that the current account-level state is what you need it to be. {: shortdesc}

1. Create or upgrade your account to a billable account ({{site.data.keyword.cloud_notm}} Pay-As-You-Go or Subscription).

2. Set up an API key for {{site.data.keyword.containerlong_notm}} in the region and resource groups where you want to create clusters. Assign the API key with the required service and infrastructure permissions to create clusters. Are you the account owner? You already have the necessary permissions! When you create a cluster, the API key for that region and resource group is set with your credentials. {: tip}

3. Verify that you as a user (not just the API key) have the required permissions to create clusters.

   1. From the {{site.data.keyword.cloud_notm}} console{: external} menu bar, click Manage > Access (IAM).
   2. Click the Users page, and then from the table, select yourself.
   3. From the Access policies tab, confirm that you have the required permissions to create clusters. Make sure that your account administrator does not assign you the Administrator platform access role at the same time as scoping the access policy to a namespace.

4. If your account uses multiple resource groups, figure out your account's strategy for managing resource groups.

   • The cluster is created in the resource group that you target when you log in to {{site.data.keyword.cloud_notm}}. If you don't target a resource group, the default resource group is automatically targeted. Free clusters are created in the default resource group.
   • If you want to create a cluster in a different resource group than the default, you need at least the Viewer role for the resource group. If you don't have any role for the resource group, your cluster is created in the default resource group.
   • You can't change a cluster's resource group.
   • If you need to use the ibmcloud ks cluster service bind command to integrate with an {{site.data.keyword.cloud_notm}} service, that service must be in the same resource group as the cluster. Services that don't use resource groups like {{site.data.keyword.registrylong_notm}} or that don't need service binding like {{site.data.keyword.la_full_notm}} work even if the cluster is in a different resource group.
   • Consider giving clusters unique names across resource groups and regions in your account to avoid naming conflicts. You can't rename a cluster.

5. Classic clusters only: Consider creating a reservation to lock in a discount over 1 or 3 year terms for your worker nodes. After you create the cluster, add worker pools that use the reserved instances. Typical savings range between 30-50% compared to regular worker node costs.

6. Standard clusters: Set up your IBM Cloud infrastructure networking to allow worker-to-master and user-to-master communication. Your cluster network setup varies with the infrastructure provider that you choose (classic or VPC). For more information, see Planning your cluster network setup.

   • VPC clusters only: Your VPC clusters are created with a public and a private cloud service endpoint by default. Optional: If you want your VPC clusters to communicate with classic clusters over the private network interface, you can choose to set up classic infrastructure access from the VPC that your cluster is in. Note that you can set up classic infrastructure access for only one VPC per region and Virtual Routing and Forwarding (VRF) is required in your {{site.data.keyword.cloud_notm}} account. For more information, see Setting up access to your Classic Infrastructure from VPC.

   • Classic clusters only, VRF and service endpoint enabled accounts: You must set up your account to use VRF and service endpoints to support scenarios such as running internet-facing workloads and extending your on-premises data center. After you set up the account, your VPC and classic clusters are created with a public and a private cloud service endpoint by default.

     1. Enable VRF in your IBM Cloud infrastructure account. To check whether a VRF is already enabled, use the ibmcloud account show command.
     2. Enable your {{site.data.keyword.cloud_notm}} account to use service endpoints.

   • Classic clusters only, Non-VRF and non-service endpoint accounts: If you don't set up your account to use VRF and service endpoints, you can create only classic clusters that use VLAN spanning to communicate with each other on the public and private network.

     • To use the public cloud service endpoint only (run internet-facing workloads), enable VLAN spanning for your IBM Cloud infrastructure account so that your worker nodes can communicate with each other on the private network. To perform this action, you need the Network > Manage Network VLAN Spanning infrastructure permission, or you can request the account owner to enable it. To check whether VLAN spanning is already enabled, use the ibmcloud ks vlan spanning get --region <region> command.
     • To use a gateway appliance (extend your on-premises data center), enable VLAN spanning for your IBM Cloud infrastructure account so that your worker nodes can communicate with each other on the private network. To perform this action, you need the Network > Manage Network VLAN Spanning infrastructure permission, or you can request the account owner to enable it. To check whether VLAN spanning is already enabled, use the ibmcloud ks vlan spanning get --region <region> command.
       1. Configure a gateway appliance to connect your cluster to the on-premises network. For example, you might choose to set up a Virtual Router Appliance or a Fortigate Security Appliance to act as your firewall to allow required network traffic and to block unwanted network traffic.
       2. Open up the required private IP addresses and ports for each region so that the master and the worker nodes can communicate and for the {{site.data.keyword.cloud_notm}} services that you plan to use.

Deciding on your cluster setup

{: #prepare_cluster_level} {: help} {: support}

After you set up your account to create clusters, decide on the setup for your cluster. You must make these decisions every time that you create a cluster. You can click on the options in the following decision tree image for more information, such as comparisons of free and standard, Kubernetes and {{site.data.keyword.redhat_openshift_notm}}, or VPC and classic clusters. {: shortdesc}

Next steps

{: #next_steps}

When the cluster is up and running, you can check out the following cluster administration tasks:

• If you created the cluster in a multizone capable zone, spread worker nodes by adding a zone to your cluster.
• Deploy an app in your cluster.
• Set up your own private registry in {{site.data.keyword.cloud_notm}} to store and share Docker images with other users.
• Set up the cluster autoscaler to automatically add or remove worker nodes from your worker pools based on your workload resource requests.
• Control who can create pods in your cluster with pod security policies.
• Enable the Istio managed add-on to extend your cluster capabilities.

Then, you can check out the following network configuration steps for your cluster setup:

• Classic clusters:
  • Isolate networking workloads to edge worker nodes in classic clusters without a gateway.
  • Expose your apps with public networking services or private networking services.
  • Connect your cluster with services in private networks outside of your {{site.data.keyword.cloud_notm}} account by setting up {{site.data.keyword.dl_full_notm}} or the strongSwan IPSec VPN service.
  • Create Calico host network policies to isolate your cluster on the public network and on the private network.
  • If you use a gateway appliance, such as a Virtual Router Appliance (VRA), open up the required ports and IP addresses in the public firewall to permit inbound traffic to networking services. If you also have a firewall on the private network, allow communication between worker nodes and let your cluster access infrastructure resources over the private network.
• VPC clusters:
  • Expose your apps with public networking services or private networking services.
  • Connect your cluster with services in private networks outside of your {{site.data.keyword.cloud_notm}} account or with resources in other VPCs by setting up the {{site.data.keyword.vpc_short}} VPN.
  • Add rules to the security group for your worker nodes to control ingress and egress traffic to your VPC subnets.