GDC air-gapped 提供兩個層級的管理平面 API，可建立及管理 GDC 資源類型：全域 API 和區域 API。
全域和區域 API 都是 Kubernetes 宣告式 API，在不同端點提供服務，而 GDC 資源則以 Kubernetes 自訂資源的形式，在 API 伺服器中表示。全球 API 伺服器共用分散在各區域的單一 etcd 叢集，以提供強烈一致性與容錯能力，但與區域 API 伺服器相比，延遲時間較長，每秒寫入查詢次數 (QPS) 也較少。在每個機構中，區域管理 API 伺服器會提供區域 API，供管理員和開發人員管理區域資源；全域管理 API 伺服器則會提供全域 API，供管理多區域資源。
# Check all possible clusters, as your kubeconfig file may have multiple contexts:
kubectlconfigview\-ojsonpath='{"Cluster name\tServer\n"}{range.clusters[*]}{.name}{"\t"}{.cluster.server}{"\n"}{end}'# Select name of cluster you want to interact with from the previous output:exportCLUSTER_NAME="[YOUR_CLUSTER]"APISERVER=$(kubectlconfigview-ojsonpath="{.clusters[?(@.name==\"$CLUSTER_NAME\")].cluster.server}")TOKEN=$(kubectlgetsecret$(kubectlgetsecrets|grepdefault|cut-f1-d' ')\-ojsonpath='{.data.token}'|base64--decode)
[[["容易理解","easyToUnderstand","thumb-up"],["確實解決了我的問題","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["難以理解","hardToUnderstand","thumb-down"],["資訊或程式碼範例有誤","incorrectInformationOrSampleCode","thumb-down"],["缺少我需要的資訊/範例","missingTheInformationSamplesINeed","thumb-down"],["翻譯問題","translationIssue","thumb-down"],["其他","otherDown","thumb-down"]],["上次更新時間：2025-09-04 (世界標準時間)。"],[[["\u003cp\u003eGoogle Distributed Cloud (GDC) air-gapped appliance APIs are programmatic interfaces to platform services, primarily using Kubernetes Resource Model (KRM) for control plane operations like resource management.\u003c/p\u003e\n"],["\u003cp\u003eGDC APIs include Kubernetes-based APIs, which are extensions of the open-source Kubernetes API and use HTTP-based RESTful APIs, as well as non-Kubernetes APIs like Vertex pre-trained AI APIs, which may also support gRPC.\u003c/p\u003e\n"],["\u003cp\u003eAccess to GDC APIs is available through the gdcloud CLI tools or the GDC console, and while the tools are suitable for exploration, direct API use is recommended for automated or programmatic access.\u003c/p\u003e\n"],["\u003cp\u003eThe Kubernetes API is declarative, and its extensions are custom resources managed by software that reconciles the real state of the system with the desired state, and the \u003ccode\u003ekubectl\u003c/code\u003e CLI is the primary tool for direct interaction.\u003c/p\u003e\n"],["\u003cp\u003eGDC APIs support Transport Layer Security (TLS) encryption, which is handled automatically by Kubernetes or GDC client libraries, while users of custom HTTP or gRPC clients must manage authentication, including TLS.\u003c/p\u003e\n"]]],[],null,["# Google Distributed Cloud air-gapped appliance APIs overview\n\nGoogle Distributed Cloud (GDC) air-gapped appliance application programming interfaces (APIs) are\nprogrammatic interfaces to the GDC platform services.\nGoogle builds the control-plane APIs on top of Kubernetes, using the\nKubernetes Resource Model (KRM). The control plane performs resource management\nfor services such as creation, deletion, and updates.\n\nSpecific services have these APIs and their own data-plane APIs, which can be XML,\nJSON, or gRPC-based. These are outlined in their respective sections on this page.\n\nAbout GDC APIs\n--------------\n\nThere are two types of GDC APIs: those that are\nKubernetes-based and those that are not. Many GDC APIs\nare extensions to the open source Kubernetes API. They use Kubernetes custom\nresources and rely on the KRM. These APIs, like the Kubernetes API, are\nHTTP-based RESTful APIs, accepting and returning JSON as the default, or in\nProtobuf. The API endpoint is the relevant Kubernetes server.\n\nOther, non-Kubernetes based GDC APIs, such as the Vertex\npre-trained AI APIs, have their own endpoints. In addition to supporting HTTP,\nsome of these APIs may also be accessible by gRPC, the open-source remote-procedure\ncall framework. For more information on specific APIs, see their dedicated documentation\nin the vertical navigation menu.\n\nTo access GDC APIs, use the [gdcloud CLI tools](/distributed-cloud/hosted/docs/latest/appliance/resources/gdcloud-overview)\nor GDC console.\n\nAbout the Kubernetes API and the KRM\n------------------------------------\n\nAs many of the GDC APIs are extensions to the Kubernetes\nAPI and rely on the KRM, an understanding of these concepts help you take\nadvantage of GDC APIs to their full extent.\n\nThe Kubernetes API is fully declarative, and everything in the Kubernetes API\nis a resource that follows the KRM. API clients, both human and machine,\nact on those resources, often with create, read, update, and delete\n(CRUD) operations. The Kubernetes database stores the resource and\nrepresents the state of the system. Kubernetes continuously watches\nthose resources and reconciles the real state of the system with the desired\nstate. For example, if you update a `Deployment` resource to indicate that you\nwant five replicas of your container instead of four, Kubernetes detects\nthe change in the desired number of replicas and creates an additional\ncontainer.\n\nFor the core Kubernetes API, Kubernetes performs the reconciliation between\ndesired and real states itself. The Kubernetes API extensions are\ncustom resources that are not part of the core Kubernetes API. The custom\nsoftware continuously watches and interacts with the Kubernetes API and\nperforms the reconciliation.\n\nTo learn more about the Kubernetes API and the Kubernetes resource model, read\nthe official Kubernetes documentation.\n\n- Kubernetes API Overview, at [*https://kubernetes.io/docs/reference/using-api/*](https://kubernetes.io/docs/reference/using-api/)\n- Kubernetes API Concepts, at [*https://kubernetes.io/docs/reference/using-api/api-concepts/*](https://kubernetes.io/docs/reference/using-api/api-concepts/)\n- The Kubernetes Resource Model (KRM), at [*https://github.com/kubernetes/design-proposals-archive/blob/main/architecture/resource-management.md*](https://github.com/kubernetes/design-proposals-archive/blob/main/architecture/resource-management.md)\n\nGlobal and zonal APIs\n---------------------\n\nResources in GDC air-gapped are either zonal resources\nor global resources. Zonal resources operate within a single zone independently,\nand a zonal outage can affect some or all of the resources in that zone. Global\nresources operate with redundancy across multiple zones for fault tolerance.\n| **Note:** The multi-zone management system is a [Preview](/distributed-cloud/hosted/docs/latest/appliance/resources/feature-stages#preview) feature.\n\nGDC air-gapped offers two levels of management plane\nAPIs to create and manage both GDC resource types:\nglobal APIs and zonal APIs.\n\nBoth global and zonal APIs are Kubernetes declarative APIs served at different\nendpoints, and GDC resources are represented as\nKubernetes custom resources in the API servers. The global API servers share a\nsingle etcd cluster distributed across zones to provide strong consistency with\nfault tolerance, at the cost of higher latency and reduced write queries per\nsecond (QPS) compared to the zonal API servers. In every organization, a\nzonal management API server provides the zonal API for administrators and\ndevelopers to manage zonal resources, and a global management API server\nprovides the global API to manage multi-zone resources.\n\nGDC APIs access\n---------------\n\nBoth the gdcloud CLI tools and the GDC console leverage\nthe GDC APIs. Google recommends that you use those to\nexplore GDC or to do one-off operations. However, if\nyou use automated or programmatic access to GDC, Google\nrecommends that you use the GDC APIs directly.\n\n### HTTP and gRPC support\n\nMost GDC APIs provide a JSON HTTP interface that you\ncall directly. The Kubernetes-based APIs use the Kubernetes\nclient libraries. Some non-Kubernetes GDC APIs have a\ngRPC interface, which provides improved performance and usability. Google also\nprovides client libraries for GDC APIs that aren't based\non Kubernetes.\n\nTo read more about gRPC, go to [*https://grpc.io/*](https://grpc.io/).\n\n### TLS encryption\n\nAll GDC APIs accept requests using the Transport Layer\nSecurity (TLS) encryption.\n\n- If you are using one of the Kubernetes or GDC client libraries, the library handles in-transit encryption for you.\n- If you are using your own HTTP or gRPC client, you must authenticate with GDC, which requires TLS. For gRPC, follow the instructions in the gRPC authentication guide at [*https://grpc.io/docs/guides/auth/*](https://grpc.io/docs/guides/auth/).\n\n| **Note:** GDC recommends that you use existing clients, especially ones Google provides, to interact with GDC APIs. Creating your own API client is an arduous software-engineering task that, if done incorrectly, might lead to unforeseen behaviors in your systems that are difficult to diagnose.\n\n### Access the Kubernetes API and Kubernetes-based APIs\n\nThe `kubectl` Kubernetes CLI is the primary way to work directly with the\nKubernetes API and any Kubernetes-based APIs.\n\n#### Access with kubectl\n\nWhen accessing the Kubernetes API for the first time, use the\nKubernetes command-line tool, `kubectl`.\n\nTo access a cluster, you need the cluster location information and the credentials\nto access it. See the [Sign in](/distributed-cloud/hosted/docs/latest/appliance/platform/pa-user/iam/sign-in#cli)\nsection to learn how to get access to those credentials.\n\nExamine your current `kubectl` configuration and see the clusters to which you have\naccess: \n\n kubectl config view\n\n#### Direct access to the API with an HTTP client\n\nThe following are ways to directly access the REST API with an HTTP client like\n`curl`, `wget`, or a browser:\n\n- Rely on `kubectl` to handle the authentication by using it in proxy mode.\n- Handle the authentication yourself.\n\n##### Run kubectl proxy\n\nThe `kubectl proxy` command runs `kubectl` in a mode where it acts as a reverse\nproxy. This command connects to the `apiserver` and manages the authentication.\n\nRunning `kubectl` in proxy mode uses the stored API server location and\nverifies the identity of the API server using a certificate. This method guards\nagainst man-in-the-middle (MITM) attacks.\n\nThe following example shows how to use the `kubectl proxy` command: \n\n kubectl proxy --port=8080 &\n\nOnce the `kubectl` proxy is running, you can explore the API with `curl`, `wget`,\nor a browser, as shown in the following: \n\n $ curl http://localhost:8080/api/\n {\n \"versions\": [\n \"v1\"\n ],\n \"serverAddressByClientCIDRs\": [\n {\n \"clientCIDR\": \"0.0.0.0/0\",\n \"serverAddress\": \"10.0.1.149:443\"\n }\n ]\n }\n\n##### Run without kubectl proxy\n\nIf you don't want to run `kubectl` in proxy mode, you can pass an authentication\ntoken directly to the `apiserver`. Replace \u003cvar translate=\"no\"\u003e[YOUR_CLUSTER]\u003c/var\u003e\nwith the name of the cluster you want to interact with in the following commands: \n\n # Check all possible clusters, as your kubeconfig file may have multiple contexts:\n kubectl config view \\\n -o jsonpath='{\"Cluster name\\tServer\\n\"}{range.clusters[*]}{.name}{\"\\t\"}{.cluster.server}{\"\\n\"}{end}'\n # Select name of cluster you want to interact with from the previous output:\n export CLUSTER_NAME=\"\u003cvar translate=\"no\"\u003e[YOUR_CLUSTER]\u003c/var\u003e\"\n APISERVER=$(kubectl config view -o jsonpath=\"{.clusters[?(@.name==\\\"$CLUSTER_NAME\\\")].cluster.server}\")\n TOKEN=$(kubectl get secret $(kubectl get secrets | grep default | cut -f1 -d ' ') \\\n -o jsonpath='{.data.token}' | base64 --decode)\n\nAfter you have exported the token in the `$TOKEN` environment variable,\nuse it with a tool like `curl` by adding the HTTP header `Authorization: Bearer\n$TOKEN` as shown in the following example: \n\n $ curl -k $APISERVER/api --header \"Authorization: Bearer $TOKEN\"\n {\n \"kind\": \"APIVersions\",\n \"versions\": [\n \"v1\"\n ],\n \"serverAddressByClientCIDRs\": [\n {\n \"clientCIDR\": \"0.0.0.0/0\",\n \"serverAddress\": \"10.0.1.149:443\"\n }\n ]\n }"]]
