Global and zonal resources

This document explains the differences between global and zonal resources, and how they operate in a multi-zone universe. Google Distributed Cloud (GDC) air-gapped provides different deployment areas for your resources so you can implement high availability strategies for your workloads and services. You must understand the multi-zone architecture and how resources span those zones to effectively plan for highly available applications.

This document is for IT administrators within the platform administrator group who are responsible for developing disaster recovery workflows, and application developers within the application operator group who are responsible for developing and maintaining applications in a GDC universe.

For more information, see Audiences for GDC air-gapped documentation.

Resource types in GDC

GDC air-gapped operates as a multi-zone universe. This operating model uses two resource types:

  • Zonal resource: Operates within a single zone independently, and is not managed outside the scope of that zone. A zonal outage can affect a zonal resource since the resource does not function outside the zone. You deploy a zonal resource to the zonal management API server, or more commonly referred to as the management API server.
  • Global resource: Operates with redundancy across multiple zones for fault tolerance, and is accessible by any resource in any zone. You deploy a global resource to the global management API server, or more commonly referred to as the global API server.

Zonal and global resources are managed differently by the GDC system with the use of distinct management API servers. An API server provides a single endpoint for creating, managing, and deleting API resources with a strongly consistent storage backend. GDC provides interfaces so you can effectively manage your resources in the various API servers within your universe.

There is always only one global API server for your universe. Likewise, there is a zonal management API server for each zone that you operate. Even if you operate in a single zone environment, there is one global API server and a zonal management API server for the single zone.

A universe manages a global API server that spans all zones, and zonal API servers dedicated for each zone.

This diagram illustrates a three zone GDC universe. Each zone has an independent zonal management API server, which manages the zonal resources that live within the scope of that zone. The universe also provides a global API server, which manages the global resources, such as projects, that span all zones.

You must have an understanding of GDC's global resource management architecture to appropriately deploy your resources for high availability. While some resources can be deployed both globally or operate in a single zone independently, there are others that are global or zonal only. Refer to the appropriate documentation of a resource type for more information.

Interfaces for resource management

GDC provides multiple surfaces that each provide mechanisms to appropriately deploy your zonal or global resource to a designated API server:

  • GDC console: A console interface that gives access to your resources across your universe.
  • gdcloud CLI: A dedicated CLI tool for GDC air-gapped, which gives zonal and global configurations and flags to manage all resource types.
  • Management APIs: Management plane APIs that give you total control over fine-tuning your resource types zonally and globally.
  • Terraform: An infrastructure-as-code (IaC) tool that lets you provision and manage cloud infrastructure zonally and globally.

You can choose the surface to manage your resources based on your needs and preferences. For more information about how to use each surface to manage your resources in a multi-zone universe, see Manage resources across zones.

GDC console

The GDC console for a given organization is accessible from every zone within the same universe. Therefore, you can use the GDC console to manage all global and zonal resources within an organization.

The GDC console provides several ways to view and manage your resources based on their deployment location:

  • Navigate using a fully qualified domain name (FQDN): Use the global FQDN to automatically resolve to the most appropriate zonal console endpoint. If the global FQDN fails to resolve in a disruption, you can use the zonal FQDN to navigate to a specific console endpoint in a target zone.
  • Manage zonal resource creation: Use the zone picker on select resource creation pages to determine where to create a zonal resource. The zone picker is not visible when you create a global resource.
  • View existing resources across zones: View zonal resources by zone in the GDC console. You can use the zone picker to select from which zone to view the list of resources.
  • Be aware of zonal connectivity status: Monitor your zone's connectivity status by reviewing notifications in the GDC console. Notifications could alert you of a zonal outage that might block you from modifying resources in that zone.

For more information on how to use the GDC console to create and manage your resources, see the corresponding resource documentation.

gdcloud CLI

The gdcloud CLI provides the following ways to interact with the zonal or global API server to manage your resources:

  • Configure a zonal or global console URL: Sign in to the zonal or global console URL using the CLI.
  • Define a zonal command flag: Use a zonal CLI flag for specific zone actions.

The global URL is what is configured by default when initializing the gdcloud CLI. You can update your gdcloud CLI configuration to set zonal URLs and sign in to them to complete zone-specific tasks.

Likewise, the gdcloud CLI offers a --zone flag that you can set for many resource management tasks across command groups. When signed in to the global URL configuration, your CLI actions on global resources are applied to all zones for which they are in scope.

For more information on the gdcloud CLI, see the gdcloud CLI overview.

Management APIs

GDC air-gapped offers two levels of management plane APIs to create and manage both global and zonal resources: global APIs and zonal APIs.

Both global and zonal APIs are Kubernetes declarative APIs served at different endpoints, and GDC resources are represented as Kubernetes custom resources in the API servers. In every organization, a zonal management API server provides the zonal API for administrators and developers to manage zonal resources, and a global management API server provides the global API to manage global resources.

For more information on APIs in GDC, see the APIs overview.

Terraform

GDC air-gapped offers a seamless way to deploy and manage all your resource types using Terraform. You use the Kubernetes Provider plugin to call the available zonal and global management APIs using industry standard Terraform lifecycle management.

For more information, see the Terraform overview.

What's next