このページは Cloud Translation API によって翻訳されました。

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

Vertex 事前トレーニング済み AI API などの Kubernetes ベース以外の GDC API には、独自のエンドポイントがあります。HTTP のサポートに加えて、これらの API の一部は、オープンソースのリモートプロシージャコールフレームワークである 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 air-gapped では、GDC リソースタイプ（グローバル API とゾーン API）の両方を作成して管理するために、2 つのレベルの管理プレーン API が提供されています。

グローバル 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 クライアントを使用している場合は、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

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}")

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

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

$ 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"
    }
  ]
}