プロジェクトにログインする

このページでは、Google Distributed Cloud（GDC）エアギャップ内でワークロードとリソースにアクセスして管理する方法について説明します。認証方法、ゾーンリソースとグローバル リソースの kubeconfig ファイルの生成方法、セッションの非アクティブ状態の管理方法について説明します。これらのプロセスを理解することで、プロジェクトとワークロードへの安全で信頼性の高いアクセスを確保できます。

このページは、GDC リソースを使用するプラットフォーム管理者グループ（IT 管理者など）またはアプリケーション オペレーター グループ（アプリケーション デベロッパーなど）のユーザーを対象としています。詳細については、GDC エアギャップ ドキュメントの対象読者をご覧ください。

ワークロードには、GDC コンソール、gdcloud CLI、または kubectl CLI を使用してアクセスできます。

アカウントを認証してアクセスする

GDC コンソールまたはクラスタにログインするには、次の手順に沿って操作します。

コンソール

新しいブラウザタブで次の URL を開き、Distributed Cloud ユーザー インターフェース（UI）にアクセスします。

https://GDC_URL

GDC_URL は、インフラストラクチャ オペレーター（IO）が提供する Distributed Cloud へのアクセスに使用するドメイン名に置き換えます。URL を初めて開くときに、インフラストラクチャ オペレーター（IO）がページを構成している場合、Distributed Cloud は ID プロバイダのログインページにリダイレクトします。

たとえば、次の画像は、org-1 という名前の組織のコンソール UI にログインしています。

gdcloud

gdcloud CLI にログインするときは、gdcloud auth login コマンドを使用して、gdcloud CLI に対するプリンシパルを認証します。gdcloud CLI は、そのプリンシパルを使用して、 Google Cloud のリソースとサービスを管理するための認証と認可を行います。

ログインする前に、次のことを確認してください。

• gdcloud CLI バイナリをダウンロードしてシステムにインストールします。詳細については、gdcloud CLI をダウンロードするをご覧ください。
• gdcloud CLI のデフォルト構成を設定して初期化します。ログイン構成エンドポイントの取得に使用される正しい組織 URL を設定してください。詳細については、gdcloud CLI のインストールをご覧ください。
• kubectl CLI をインストールします。
• 認証プラグイン gdcloud-k8s-auth-plugin をインストールします。詳細については、gdcloud CLI 認証をご覧ください。

重要: 次の手順は、root アカウントではなく、ユーザー アカウントを使用してシステムで実行します。gdcloud CLI は、root モードではブラウザを自動的に開きません。

Management API サーバーまたは Kubernetes クラスタにログインするには、次の操作を行います。

• Management API サーバー:

1. Management API サーバーの kubeconfig ファイルを保存するパスをエクスポートします。

   export KUBECONFIG=MANAGEMENT_API_SERVER
   

   MANAGEMENT_API_SERVER は、kubeconfig ファイルを保存するディレクトリのパスに置き換えます。

2. gdcloud CLI インスタンスを認証してログインします。認証には次の 2 つの方法があります。

   • 標準のブラウザ ログイン: ブラウザからログインする場合は、この認証フローを使用します。

     gdcloud auth login
     

   • セカンダリ デバイスのログイン: プライマリ デバイスでブラウザを使用できない場合は、この認証フローを使用します。このフローでは、ブラウザにアクセスできないプライマリ デバイスでログインを開始し、ブラウザにアクセスできるセカンダリ デバイスでログインを続行します。

     ブラウザがインストールされていないメインのデバイスでログインを開始します。

     gdcloud auth login --no-browser
     

     KUBECONFIG 環境変数は、組織内のすべての API サーバーとクラスタの kubeconfig ファイルで更新されます。KUBECONFIG 変数が設定されていない場合、kubectl CLI は $HOME/.kube/config に保存されているデフォルトの kubeconfig ファイルを使用します。

     kubeconfig ファイルの編集をスキップするには、コマンドに --skip-kubeconfig-update フラグを追加します。次に例を示します。

     gdcloud auth login --no-browser --skip-kubeconfig-update
     

     出力された gdcloud CLI コマンド出力をコピーし、ブラウザにアクセスできるマシンで実行します。

3. ウェブページの手順に沿ってログイン プロセスを完了します。

   ログインが正常に完了すると、ブラウザに「Authentication successful. このウィンドウを閉じてください。

4. 端末に表示される手順に沿って操作します。ログインに成功すると、ターミナルに「ログインしました」というメッセージが表示されます。

   注: エラー x509: certificate signed by unknown authority が表示された場合、ワークステーションは GDC で使用されている CA 証明書を信頼していません。組織の手順に沿って、ワークステーションの信頼できる証明書ストアを確認します。
   警告: 未検証の証明書で --login-config-cert を使用すると、中間者攻撃に対して脆弱になります。不明なソースからの CA 証明書を信頼するのではなく、ワークステーションのトラストストアのみに依存するようにしてください。

• Kubernetes クラスタ:

1. gdcloud CLI インスタンスを認証してログインします。認証には次の 2 つの方法があります。

   • 標準のブラウザ ログイン: ブラウザからログインする場合は、この認証フローを使用します。

     gdcloud auth login
     

   • セカンダリ デバイスのログイン: プライマリ デバイスでブラウザを使用できない場合は、この認証フローを使用します。このフローでは、ブラウザにアクセスできないプライマリ デバイスでログインを開始し、ブラウザにアクセスできるセカンダリ デバイスでログインを続行します。

     1. ブラウザがインストールされていないメインのデバイスでログインを開始します。

        gdcloud auth login --no-browser
        

        プライマリ デバイスのコマンドは、ステップ c でセカンダリ デバイスで実行する必要がある別の gdcloud コマンドを出力します。

     2. ステップ 1 を繰り返して、セカンダリ デバイスに証明書をダウンロードします。

     3. 手順 a でメインのデバイスに表示されたコマンドを入力して、サブのデバイスでログインを完了します。

   この操作により、ブラウザが開き、構成済みの ID プロバイダ（IdP）にログインします。ログインするには、gdcloud CLI の初期設定時に設定したユーザーとパスワードを指定します。

   注: エラー x509: certificate signed by unknown authority が表示された場合、ワークステーションは GDC で使用されている CA 証明書を信頼していません。組織の手順に沿って、ワークステーションの信頼できる証明書ストアを確認します。
   警告: 未検証の証明書で --login-config-cert を使用すると、中間者攻撃に対して脆弱になります。不明なソースからの CA 証明書を信頼するのではなく、ワークステーションのトラストストアのみに依存するようにしてください。

2. ユーザー ID の kubeconfig ファイルを変数としてエクスポートします。

   export KUBECONFIG=/tmp/CLUSTER_NAME-ZONE-kubeconfig-with-user-identity.yaml
   

3. ユーザー ID を使用して、ゾーンクラスタの kubeconfig ファイルを生成します。

   gdcloud clusters get-credentials CLUSTER_NAME --zone ZONE
   

   ZONE は、ゾーン名に置き換えます。

   重要: グローバル apiserver はどのゾーンにもバインドされていないため、zone フラグを指定せずにこのコマンドを実行して、グローバル apiserver の kubeconfig を生成します。gdcloud clusters get-credentials global-api。
   注: 使用可能なクラスタ名のリストは、ログイン構成 URL
   https://GDC_URL/.well-known/login-config で確認できます。

   kubeconfig ファイルがユーザー ID で生成されます。次の YAML ファイルに例を示します。

   apiVersion: v1
   clusters:
   - cluster:
     certificate-authority-data: <REDACTED>
     server: https://10.200.0.32:443
   name: cluster-name
   contexts:
   - context:
     cluster: cluster-name
     user: cluster-name-anthos-default-user
   name: cluster-name-cluster-name-anthos-default-user
   current-context: cluster-name-cluster-name-anthos-default-user
   kind: Config
   preferences: {}
   users:
   - name: cluster-name-anthos-default-user
   user:
     exec:
       apiVersion: client.authentication.k8s.io/v1
       args:
       - --audience=root-admin
       command: gdcloud-k8s-auth-plugin
       env: null
       installHint: Run 'gdcloud components install gdcloud-k8s-auth-plugin' to use plugin
       interactiveMode: Never
       provideClusterInfo: false
   

4. クラスタにアクセスできることを確認するには、生成された kubeconfig ファイルを使用してユーザー ID でログインします。

   kubectl --kubeconfig /tmp/admin-kubeconfig-with-user-identity.yaml version
   

ログアウト

GDC コンソールからログアウトする手順は次のとおりです。

コンソール

メニューバーの [ログアウト] をクリックします。

gdcloud

CLI からログアウトします。

gdcloud auth revoke

注: Kubernetes リソースに依存するページは機能しません。Chrome デバッグ コンソールに、レスポンスの「forbidden」エラーが表示されます。このエラーは、ユーザーに権限が付与されておらず、ロールにバインドされていないために発生します。権限を付与する手順については、リソースへのアクセス権を付与するをご覧ください。

kubeconfig ファイルを手動で生成する

KRM API を直接呼び出して kubectl CLI でリソースを管理している場合は、管理しているリソースの種類に応じて、リソースをホストするクラスタまたは API サーバーの kubeconfig ファイルを生成する必要があります。

また、GDC ユニバースの構成を把握して、ゾーンリソースをデプロイするゾーン、またはグローバル リソースのグローバル API サーバーを決定する必要があります。詳細については、グローバル API サーバーとゾーン API サーバーをご覧ください。

操作するリソースがグローバル リソースかゾーンリソースかを判断します。不明な点がある場合は、リソース専用のドキュメントをご覧ください。

リソースタイプに応じて、該当する設定を完了します。

ゾーン Management API サーバーのリソース

ゾーン管理 API サーバーの kubeconfig ファイルを生成するには、次の手順を行います。

1. 利用可能なすべてのゾーンを表示します。

   gdcloud zones list
   

   カスタム リソースをホストするゾーンの名前をメモします。

2. ZONE 環境変数を、ゾーンリソースをホストするゾーンに設定します。

   export ZONE="ZONE"
   

   ZONE は、ゾーン名に置き換えます。

3. MANAGEMENT_API_SERVER 環境変数を設定します。

   export MANAGEMENT_API_SERVER="ORG_NAME-admin"
   

   ORG_NAME は、組織の名前（org-1 など）に置き換えます。

4. ターゲット ゾーンの Management API サーバーの kubeconfig ファイルを生成し、認証情報を検証します。

   export KUBECONFIG=${HOME}/${MANAGEMENT_API_SERVER:?}-kubeconfig.yaml
   rm ${KUBECONFIG:?}
   gdcloud clusters get-credentials ${MANAGEMENT_API_SERVER:?} --zone ${ZONE:?}
   [[ $(kubectl config current-context) == *${MANAGEMENT_API_SERVER:?}* ]] && echo "Success. Your kubeconfig is at $KUBECONFIG" || echo "Failure"
   

   rm ${KUBECONFIG:?} コマンドは、ホーム ディレクトリにある既存の kubeconfig ファイルを削除します。新しい kubeconfig ファイルを生成すると、既存のファイルが上書きされます。既存のファイルを上書きまたは削除しない場合は、別の安全な場所にバックアップします。

Kubernetes ゾーンクラスタのリソース

次の手順に沿って、ゾーン Kubernetes クラスタの kubeconfig ファイルを生成します。

1. 利用可能なすべてのゾーンを表示します。

   gdcloud zones list
   

   カスタム リソースをホストするゾーンの名前をメモします。

2. ZONE 環境変数を、Kubernetes クラスタをホストするゾーンに設定します。

   export ZONE="ZONE"
   

   ZONE は、ゾーン名に置き換えます。

3. KUBERNETES_CLUSTER 環境変数を設定します。

   export KUBERNETES_CLUSTER="KUBERNETES_CLUSTER_NAME"
   

   KUBERNETES_CLUSTER_NAME は、Kubernetes クラスタの名前に置き換えます。

4. ターゲット ゾーン変数の Kubernetes クラスタ kubeconfig ファイルを生成し、認証情報を検証します。

   export KUBECONFIG=${HOME}/${KUBERNETES_CLUSTER:?}-kubeconfig.yaml
   rm ${KUBECONFIG:?}
   gdcloud clusters get-credentials ${KUBERNETES_CLUSTER:?} --zone ${ZONE:?}
   [[ $(kubectl config current-context) == *${KUBERNETES_CLUSTER:?}* ]] && echo "Success. Your kubeconfig is at $KUBECONFIG" || echo "Failure"
   

   rm ${KUBECONFIG:?} コマンドは、ホーム ディレクトリにある既存の kubeconfig ファイルを削除します。新しい kubeconfig ファイルを生成すると、既存のファイルが上書きされます。既存のファイルを上書きまたは削除しない場合は、別の安全な場所にバックアップします。

グローバル API サーバー リソース

グローバル API サーバーの kubeconfig ファイルを生成するには、次の手順を完了します。

1. GLOBAL_API_SERVER 環境変数を設定します。

   export GLOBAL_API_SERVER="global-api"
   

2. グローバル API サーバーの kubeconfig ファイルを生成し、認証情報を検証します。

   export KUBECONFIG=${HOME}/${GLOBAL_API_SERVER:?}-kubeconfig.yaml
   rm ${KUBECONFIG:?}
   gdcloud clusters get-credentials ${GLOBAL_API_SERVER:?}
   [[ $(kubectl config current-context) == *${GLOBAL_API_SERVER:?}* ]] && echo "Success. Your kubeconfig is at $KUBECONFIG" || echo "Failure"
   

   rm ${KUBECONFIG:?} コマンドは、ホーム ディレクトリにある既存の kubeconfig ファイルを削除します。新しい kubeconfig ファイルを生成すると、既存のファイルが上書きされます。既存のファイルを上書きまたは削除しない場合は、別の安全な場所にバックアップします。

セッションの非アクティブ ログアウト

セッションで 15 分以上操作がないと、GDC コンソールと gdcloud CLI からログアウトされます。Distributed Cloud では、セッションの非アクティブ状態とは、セッションが開いている間に、カーソルやキーボードの移動など、ユーザーによるアクティブな操作がない期間と見なされます。アクティブなセッションは、ユーザー アクティビティで最大 12 時間継続します。

コンソール

セッションが非アクティブになると、GDC コンソールからログアウトされます。非アクティブ状態が原因で GDC コンソールからログアウトされる 2 分前に、ログアウトを警告するダイアログが表示されます。

操作がないためにログアウトされると、次の画面が表示されます。

GDC コンソールに再度ログインするには、ID プロバイダを選択してログイン認証情報を追加します。モニタリング ダッシュボードなどのサービスを使用しているときに、非アクティブな状態が続いて GDC コンソールからログアウトされた場合は、再度ログインしてアクセスしてください。

gdcloud

セッションが非アクティブになると、gdcloud CLI からログアウトされます。gdcloud CLI がログアウトした後にコマンドを実行しようとすると、認可エラーが発生します。

Error: error when creating kube client: unable to create k8sclient: Unauthorized

GDC に再度ログインするには、ログインの CLI の手順に沿って操作します。

Management API サーバーを介して GDC に再度ログインすると、kubeconfig ファイルが自動的に更新されます。kubeconfig ファイルが更新されないようにするには、gdcloud auth login コマンドで --skip-kubeconfig-update フラグを使用します。

注: gdcloud init や gdcloud config など、API リクエストを行わないコマンドは、アクティビティにカウントされません。これらのコマンドを使用すると、gdcloud CLI はログアウトします。

kubectl

gdcloud CLI は、セッションが非アクティブになると kubeconfig ファイルを期限切れにします。非アクティブな状態で kubectl コマンドを実行しようとすると、認可エラーが発生します。

error: You must be logged in to the server (Unauthorized)

再度ログインして kubeconfig ファイルを使用するには、ログインの CLI の手順に沿って操作します。セッションがタイムアウトするたびに、kubeconfig ファイルを再生成する必要があります。