Locations

Classic regions with multiple data centers

If you create a classic cluster with multiple data centers, the replicas of the highly available Kubernetes master are automatically spread across the data centers. You have the option to spread your worker nodes across classic zones (data centers) to protect your apps from a zone failure. To determine whether a classic region has multiple data centers from the CLI, your can run ibmcloud ks locations and look for the value in the Multizone Metro column.

* lon05 replaces lon02. New clusters must use lon05, which supports highly available masters that are spread across zones.

Classic regions with one data center

If you create a classic cluster in a region with only one data center, the highly available master includes three replicas on separate hosts, but is not spread across classic zones.

Classic regions with one data center are managed from the regional endpoint located in the nearest region that supports classic data centers, such as mon01 to us-east or sao01 to us-south.

VPC multizone regions

VPC resources are provisioned in a region, which is a separate group of zones within a metro. The zones are mapped to separate data centers to ensure that resources are distributed evenly across zones in a multizone architecture. In the API and CLI, zones use the regional zone name in the API and command line (us-south-1), but in the console, zones use by the data center location (Dallas 1). For the data center code that the VPC zone and location corresponds to, such as us-south-1 and DAL10, see Multizone regions.

† These regions are available as multizone regions for clusters on VPC infrastructure only.

Resources in single zone clusters

Your cluster's resources remain in the data center in which the cluster is deployed, but management operations might be routed through a regional endpoint.

Your cluster's resources, including the master and worker nodes, are in the same zone that you deployed the cluster to. When you initiate local container orchestration actions, such as kubectl commands, the information is exchanged between your master and worker nodes within the same zone.

If you set up other cluster resources, such as storage, networking, compute, or apps running in pods, the resources and their data remain in the data center that you deployed your cluster to.

When you initiate cluster management actions, such as running ibmcloud ks commands, basic information about the cluster such as name, ID, user, the command is routed through a regional endpoint and the global endpoint.

Resources in multizone clusters

In multizone clusters, the cluster's resources are spread across multiple locations (zones for VPC and data centers for Classic) for higher availability.

Worker nodes are spread across multiple VPC zones or Classic data centers in the region to provide more availability for your cluster. The Kubernetes master replicas are also spread across zones or classic data centers. When you initiate local container orchestration actions, such as kubectl commands, the information is exchanged between your master and worker nodes through the global endpoint.

Other cluster resources, such as storage, networking, compute, or apps running in pods, vary in how they deploy to the zones in your cluster. For more information, review these topics:

• Setting up file storage and block storage in clusters, or choosing a multizone persistent storage solution.
• Enabling public or private access to an app by using a network load balancer (NLB) service in a cluster.
• Managing network traffic by using Ingress.
• Increasing the availability of your app.

When you initiate cluster management actions, such as running ibmcloud ks commands, basic information about the cluster, such as name, ID, user, the command is routed through the global endpoint.

Accessing resources from the CLI

1. Install the CLI.

2. Log in to your account. If applicable, target the appropriate resource group. Set the context for your cluster.

   When you log in to the IBM Cloud (ibmcloud) command line, you are prompted to select a region. However, this region does not affect the IBM Cloud Kubernetes Service plug-in (ibmcloud ks) endpoint, which still uses the global endpoint. Note that you do still need to target the resource group that your cluster is in if it is not in the default resource group.

3. Review the CLI commands.

   • Listing resources:

     • When you list resources, such as with the ibmcloud ks cluster ls, ibmcloud ks subnets, or ibmcloud ks zone ls commands, resources in all locations are returned. To filter resources by a specific location, certain commands include a --location option. For example, if you filter clusters for the wdc metro, multizone clusters in that metro and single-zone clusters in data centers (zones) within that metro are returned. If you filter clusters for the wdc06 data center (zone), multizone clusters that have a worker node in that zone and single-zone clusters in that zone are returned. ibmcloud ks cluster ls -l dal.

     • Other commands don't return resources in all locations. To run credential set/unset/get, api-key reset, and vlan spanning get commands, you must specify a region in the --region.

   • Working with resources:

     • When you use the global endpoint, you can work with resources that you have access permissions to in any location, even if you target one region and the resource that you want to work with is in another region.
     • If you have clusters with the same name in different regions, use the cluster ID when you run commands or set a region with the ibmcloud ks init command and use the cluster name when you run commands.

Accessing resources from the API

1. Get started with the API.

2. Review the API commands.

   To interact with the global IBM Cloud Kubernetes Service API, enter the command type and append global/v1/command to the endpoint.

   Example of GET /clusters global API:

   GET https://containers.cloud.ibm.com/global/v1/clusters
   

   If you need to specify a region in an API call, remove the /global parameter from the path and pass the region name in the X-Region header. To list available regions, review the Previous region column in the IBM Cloud Kubernetes Service locations table.

3. Optional: Generate a client of the API to use in automation by using the swagger.json API.