cluster-create.md

copyright	lastupdated	keywords	subcollection
years 2014, 2024	2024-01-05	containers, clusters, worker nodes, worker pools	containers

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

Preparing your account to create clusters

{: #clusters}

Complete the following steps to prepare your account for creating {{site.data.keyword.containerlong_notm}} clusters. {: shortdesc}

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.

Create or upgrade your account

{: #prepare-create-account} {: step}

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

Set up an API key

{: #prepare-create-api-key} {: step}

1. Set up an API key for {{site.data.keyword.containerlong_notm}} in the region and resource groups where you want to create clusters.
2. Assign the API key with the required service and infrastructure permissions to create clusters.

Verify your permissions

{: #prepare-verify-permissions} {: step}

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}

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.
   • 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. 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).

   • 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 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.

Create your first cluster

{: #next_steps} {: step}

• Create a classic cluster.
• Create a VPC cluster.
• Getting started with {{site.data.keyword.containerlong_notm}}.