Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

Google Distributed Cloud エアギャップ API の概要

Google Distributed Cloud（GDC）エアギャップアプリケーションプログラミングインターフェース（API）は、GDC プラットフォームサービスへのプログラマティックインターフェースです。Google は、Kubernetes リソースモデル（KRM）を使用して、Kubernetes 上にコントロールプレーン API を構築します。コントロールプレーンは、作成、削除、更新などのサービスのリソース管理を行います。

特定のサービスには、これらの API と独自のデータプレーン API（XML、JSON、または gRPC ベース）があります。このページでは、これらのサービスについてそれぞれのセクションで説明します。

GDC API について

GDC API には、Kubernetes ベースの API と、そうでない API の 2 種類があります。多くの GDC API は、オープンソースの Kubernetes API の拡張機能です。Kubernetes カスタムリソースを使用し、KRM に依存します。これらの API は、Kubernetes API と同様に、HTTP ベースの RESTful API であり、デフォルトで JSON または Protobuf で受け入れ、返します。API エンドポイントは、関連する Kubernetes サーバーです。

Vertex 事前トレーニング済み AI API など、Kubernetes ベース以外の GDC API には独自のエンドポイントがあります。これらの API の一部は、HTTP のサポートに加えて、オープンソースのリモートプロシージャコールフレームワークである gRPC からもアクセスできます。特定の API の詳細については、左側のナビゲーションメニューにある専用のドキュメントをご覧ください。

GDC API にアクセスするには、gdcloud CLI ツールまたは GDC コンソールを使用します。

Kubernetes API と KRM について

GDC API の多くは Kubernetes API の拡張機能であり、KRM に依存しているため、これらのコンセプトを理解することで、GDC API を最大限に活用できます。

Kubernetes API は完全に宣言型であり、Kubernetes API のすべてが KRM に従うリソースです。人間とマシンの両方の API クライアントは、通常、作成、読み取り、更新、削除（CRUD）オペレーションを使用して、これらのリソースを操作します。Kubernetes データベースはリソースを保存し、システムの状態を表します。Kubernetes はこれらのリソースを継続的に監視し、システムの実際の状態を望ましい状態に調整します。たとえば、Deployment リソースを更新して、コンテナのレプリカを 4 つではなく 5 つにするように指定すると、Kubernetes は必要なレプリカ数の変更を検出し、追加のコンテナを作成します。

コア Kubernetes API の場合、Kubernetes は望ましい状態と実際の状態の調整を独自に実行します。Kubernetes API 拡張機能は、コア Kubernetes API の一部ではないカスタムリソースです。カスタムソフトウェアは、Kubernetes API を継続的に監視して操作し、調整を行います。

Kubernetes API と Kubernetes リソースモデルの詳細については、Kubernetes の公式ドキュメントをご覧ください。

Kubernetes API の概要（https://kubernetes.io/docs/reference/using-api/）
Kubernetes API のコンセプト（https://kubernetes.io/docs/reference/using-api/api-concepts/）
Kubernetes Resource Model（KRM）（https://github.com/kubernetes/design-proposals-archive/blob/main/architecture/resource-management.md）

グローバル API とゾーン API

GDC エアギャップのリソースは、ゾーンリソースまたはグローバルリソースです。ゾーンリソースは単一のゾーン内で独立して動作します。ゾーンが停止すると、そのゾーン内のリソースの一部またはすべてに影響する可能性があります。グローバルリソースは、フォールトトレランスのために複数のゾーンにわたって冗長性を持って動作します。

GDC エアギャップには、グローバル API とゾーン API の 2 つのレベルの管理プレーン API が用意されており、両方の GDC リソースタイプを作成して管理できます。

グローバル API とゾーン API はどちらも、異なるエンドポイントで提供される Kubernetes 宣言型 API であり、GDC リソースは API サーバーで Kubernetes カスタムリソースとして表されます。グローバル API サーバーは、ゾーンに分散された単一の etcd クラスタを共有して、フォールトトレランスを備えた強整合性を提供します。ただし、ゾーン API サーバーと比較してレイテンシが高くなり、1 秒あたりの書き込みクエリ数（QPS）が減少します。すべての組織で、ゾーン管理 API サーバーは、管理者とデベロッパーがゾーンリソースを管理するためのゾーン API を提供し、グローバル API サーバーは、マルチゾーンリソースを管理するためのグローバル API を提供します。

GDC API へのアクセス

gdcloud CLI ツールと GDC コンソールの両方で GDC API が使用されます。Google では、これらを使用して GDC を探索するか、1 回限りのオペレーションを行うことをおすすめします。ただし、GDC への自動アクセスまたはプログラムによるアクセスを使用する場合は、GDC API を直接使用することをおすすめします。

HTTP と gRPC のサポート

ほとんどの GDC API は、直接呼び出す JSON HTTP インターフェースを備えています。Kubernetes ベースの API は、Kubernetes クライアントライブラリを使用します。一部の Kubernetes 以外の GDC API には、パフォーマンスとユーザビリティを向上させる gRPC インターフェースがあります。Google は、Kubernetes に基づいていない GDC API のクライアントライブラリも提供しています。 gRPC の詳細については、https://grpc.io/ をご覧ください。

TLS 暗号化

すべての GDC API は、Transport Layer Security（TLS）暗号化を使用してリクエストを受け入れます。

Kubernetes または GDC のクライアントライブラリのいずれかを使用している場合、ライブラリは転送中の暗号化を処理します。
独自の HTTP または gRPC クライアントを使用している場合は、GDC で認証する必要があります。これには TLS が必要です。 gRPC の場合は、https://grpc.io/docs/guides/auth/ にある gRPC 認証ガイドの手順に沿って操作します。

Kubernetes API と Kubernetes ベースの API にアクセスする

kubectl Kubernetes CLI は、Kubernetes API や Kubernetes ベースの API を直接操作する主な方法です。

kubectl を使用してアクセスする

Kubernetes API に初めてアクセスする場合は、Kubernetes コマンドラインツール kubectl を使用します。

クラスタにアクセスするには、クラスタのロケーション情報と、クラスタにアクセスするための認証情報が必要です。これらの認証情報を取得する方法については、ログインのセクションをご覧ください。

現在の kubectl 構成を調べて、アクセス可能なクラスタを確認します。

kubectl config view

API エンドポイントの説明を生成する

GDC エアギャップのすべてのサービス API で使用可能な API エンドポイントのリストを表示するには、JSON 形式の OpenAPI 仕様に沿って API の説明を生成します。API エンドポイント用に生成された JSON は、Swagger などのツールで表示できます。

次の手順に沿って、管理プレーンとデータプレーンの API エンドポイントの説明を JSON 形式で生成します。

環境と Management API サーバーの間にプロキシサーバーを作成します。
```
kubectl proxy --kubeconfig MANAGEMENT_API_SERVER
```
MANAGEMENT_API_SERVER は、Management API サーバーの kubeconfig ファイルのパスに置き換えます。詳細については、ゾーン管理 API サーバーのリソースをご覧ください。

API エンドポイントの説明のリストを JSON 形式でダウンロードします。

curl -s http://127.0.0.1:8001/openapi/v2 | jq 'if .paths then .paths = (.paths
    | with_entries(select(.key | contains(".private") | not))) else . end' > k8s_swagger.json

生成された k8s_swagger.json ファイルを Swagger などのツールで開き、API エンドポイントの説明を表示します。

HTTP クライアントを使用した API への直接アクセス

curl、wget、ブラウザなどの HTTP クライアントを使用して REST API に直接アクセスする方法は次のとおりです。

kubectl をプロキシモードで使用して、認証を処理します。
認証を自分で処理する。

kubectl proxy を実行する

kubectl proxy コマンドは、リバースプロキシとして機能するモードで kubectl を実行します。このコマンドは apiserver に接続し、認証を管理します。

プロキシモードで kubectl を実行すると、保存されている API サーバーのロケーションが使用され、証明書を使用して API サーバーの ID が検証されます。この方法は、中間者（MITM）攻撃から保護します。

次の例では、kubectl proxy コマンドの使用方法を示します。

kubectl proxy --port=8080 &

kubectl プロキシが実行されたら、次のように curl、wget、またはブラウザを使用して API を探索できます。

$ curl http://localhost:8080/api/
{
  "versions": [
    "v1"
  ],
  "serverAddressByClientCIDRs": [
    {
      "clientCIDR": "0.0.0.0/0",
      "serverAddress": "10.0.1.149:443"
    }
  ]
}

kubectl プロキシなしで実行する

kubectl をプロキシモードで実行しない場合は、認証トークンを API サーバーに直接渡すことができます。

kubeconfig ファイルに複数のコンテキストが含まれている可能性があるため、アクセス可能なすべての Kubernetes クラスタを一覧表示します。
```
kubectl config view \
    -o jsonpath='{"Cluster name\tServer\n"}{range.clusters[*]}{.name}{"\t"}{.cluster.server}{"\n"}{end}'
```
前の出力から、操作する Kubernetes クラスタの名前をエクスポートします。
```
export CLUSTER_NAME="CLUSTER_NAME"
```

Kubernetes クラスタ名を参照する API サーバーを設定します。

APISERVER=$(kubectl config view -o jsonpath="{.clusters[?(@.name==\"$CLUSTER_NAME\")].cluster.server}")

デフォルトのサービスアカウントのトークンを保持する Secret を作成します。

kubectl apply -n NAMESPACE -f - <<EOF
apiVersion: v1
kind: Secret
metadata:
  name: default-token
  annotations:
    kubernetes.io/service-account.name: default
type: kubernetes.io/service-account-token
EOF

トークンコントローラがトークンをシークレットに設定するまで待ちます。

while ! kubectl describe secret default-token -n NAMESPACE | grep -E '^token' >/dev/null; do
  echo "waiting for token..." >&2
  sleep 1
done

トークン値を設定します。

TOKEN=$(kubectl get secret default-token -n NAMESPACE \
    -o jsonpath='{.data.token}' | base64 --decode)

API にアクセスするには、次の例に示すように、HTTP ヘッダー Authorization: Bearer $TOKEN を追加して、curl などのツールでトークンを使用します。

curl -k $APISERVER/api --header "Authorization: Bearer $TOKEN"

出力は次のようになります。

{
  "kind": "APIVersions",
  "versions": [
    "v1"
  ],
  "serverAddressByClientCIDRs": [
    {
      "clientCIDR": "0.0.0.0/0",
      "serverAddress": "10.0.1.149:443"
    }
  ]
}