Stay organized with collections
Save and categorize content based on your preferences.
The Cluster API uses Kubernetes custom resources and relies on the Kubernetes
Resource Model (KRM). It manages the lifecycle of clusters in a given
organization, such as installing, upgrading, and uninstalling.
To use the Cluster API, we recommend that you use the GDC console. If
your application needs to use your own libraries to call this API, use the
following example and the full API definition to build your
requests.
Service endpoint and discovery document
The API endpoint for the Cluster API is:
https://GDCH_API_SERVER_ENDPOINT/apis/cluster.gdc.goog/v1
where GDCH_API_SERVER_ENDPOINT is the API endpoint of the
GDC API server.
Using the kubectl proxy command, you can access that URL in your browser or
with a tool such as curl to get the discovery document for the Cluster API.
The kubectl proxy command opens up a proxy to the Kubernetes API server on
your local machine. Once that command is running, you can access the document at
the following URL: http://127.0.0.1:8001/apis/cluster.gdc.goog/v1.
Example Cluster resource
The following is an example of a Cluster object configured as a user cluster:
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-03 UTC."],[[["\u003cp\u003eThe Cluster API, leveraging Kubernetes custom resources and the Kubernetes Resource Model (KRM), is used to manage cluster lifecycles, including installation, upgrades, and uninstallation.\u003c/p\u003e\n"],["\u003cp\u003eThe recommended method for interacting with the Cluster API is through the GDC console, but custom libraries can be used by referencing the provided API definition and examples.\u003c/p\u003e\n"],["\u003cp\u003eThe Cluster API endpoint is located at \u003ccode\u003ehttps://<GDCH_API_SERVER_ENDPOINT>/apis/cluster.gdc.goog/v1\u003c/code\u003e, where \u003ccode\u003e<GDCH_API_SERVER_ENDPOINT>\u003c/code\u003e represents the GDC API server's endpoint.\u003c/p\u003e\n"],["\u003cp\u003eYou can use the \u003ccode\u003ekubectl proxy\u003c/code\u003e command to access the Cluster API's discovery document at \u003ccode\u003ehttp://127.0.0.1:8001/apis/cluster.gdc.goog/v1\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eAn example \u003ccode\u003eCluster\u003c/code\u003e resource is provided, showcasing configuration details like network settings, Kubernetes version, load balancer, node pools and release channel.\u003c/p\u003e\n"]]],[],null,["# Cluster API overview\n\nThe Cluster API uses Kubernetes custom resources and relies on the Kubernetes\nResource Model (KRM). It manages the lifecycle of clusters in a given\norganization, such as installing, upgrading, and uninstalling.\n\nTo use the Cluster API, we recommend that you use the GDC console. If\nyour application needs to use your own libraries to call this API, use the\nfollowing example and the [full API definition](/distributed-cloud/hosted/docs/latest/appliance/apis/service/cluster/cluster-krm-api) to build your\nrequests.\n\nService endpoint and discovery document\n---------------------------------------\n\nThe API endpoint for the Cluster API is:\n`https://`\u003cvar translate=\"no\"\u003eGDCH_API_SERVER_ENDPOINT\u003c/var\u003e`/apis/cluster.gdc.goog/v1`\nwhere \u003cvar translate=\"no\"\u003eGDCH_API_SERVER_ENDPOINT\u003c/var\u003e is the API endpoint of the\nGDC API server.\n\nUsing the `kubectl proxy` command, you can access that URL in your browser or\nwith a tool such as `curl` to get the discovery document for the Cluster API.\nThe `kubectl proxy` command opens up a proxy to the Kubernetes API server on\nyour local machine. Once that command is running, you can access the document at\nthe following URL: `http://127.0.0.1:8001/apis/cluster.gdc.goog/v1`.\n\nExample Cluster resource\n------------------------\n\nThe following is an example of a `Cluster` object configured as a user cluster: \n\n apiVersion: cluster.gdc.goog/v1\n kind: Cluster\n metadata:\n name: user-vm-1\n namespace: platform\n spec:\n clusterNetwork:\n podCIDRSize: 21\n serviceCIDRSize: 23\n initialVersion:\n kubernetesVersion: 1.27.1-gke.700\n loadBalancer:\n ingressServiceIPSize: 21\n nodePools:\n - machineTypeName: n2-standard-8-gdc\n name: worker-node-pool\n nodeCount: 3\n releaseChannel:\n channel: UNSPECIFIED"]]
