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

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

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

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

GDC API について

GDC API には、Kubernetes ベースのものとそうでないものの 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 リソースモデル（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 が使用されます。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 クライアントを使用している場合は、TLS が必要な GDC で認証を行う必要があります。 gRPC の場合は、gRPC 認証ガイド（https://grpc.io/docs/guides/auth/）の手順に沿って操作してください。

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 などのツールで確認できます。

JSON 形式で管理プレーンとデータプレーンの API エンドポイントの説明を生成する手順は次のとおりです。

環境と管理 API サーバーの間にプロキシサーバーを作成します。
```
kubectl proxy --kubeconfig MANAGEMENT_API_SERVER
```
MANAGEMENT_API_SERVER は、管理 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 proxy を使用せずに実行する

プロキシモードで 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

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

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

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

TOKEN=$(kubectl get secret $(kubectl get secrets | grep default | cut -f1 -d ' ')  \
    -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"
    }
  ]
}