Kubernetes向けGitLabエージェントサーバーをインストールする（KAS）

GitLabと共にインストールされるコンポーネントであるエージェントサーバー。Kubernetes向けGitLabエージェントの管理に必要です。

KASという略語は、以前の名前であるKubernetes agent serverを指します。

Kubernetes用エージェントサーバーは、GitLab.comのwss://kas.gitlab.comにインストールされ、利用可能です。GitLab Self-Managedを使用している場合、デフォルトではエージェントサーバーがインストールされ、利用可能です。

インストールオプション

GitLab管理者として、エージェントサーバーのインストールを制御できます:

• Linuxパッケージインストールの場合。
• GitLab Helmチャートインストールの場合。

Linuxパッケージインストールの場合

Linuxパッケージインストール用のエージェントサーバーは、単一ノード、または複数のノードで一度に有効にできます。デフォルトでは、エージェントサーバーはws://gitlab.example.com/-/kubernetes-agent/で有効になり、利用可能です。

単一ノードでの無効化

単一ノードのエージェントサーバーを無効にするには:

1. /etc/gitlab/gitlab.rbを編集します:

   gitlab_kas['enable'] = false

2. GitLabを再設定します。

複数のノードでKASをオンにする

KASインスタンスは、既知の場所にあるRedisにプライベートアドレスを登録することで、相互に通信します。他のインスタンスがアクセスできるように、各KASがプライベートアドレスの詳細を提示するように設定する必要があります。

複数のノードでKASをオンにするには:

1. 共通設定を追加します。

2. 次のいずれかのオプションから設定を追加します:

   • オプション1 - 明示的な手動設定
   • オプション2 - 自動CIDRベースの設定
   • オプション3 - リスナー設定に基づく自動設定

3. GitLabを再設定します。

4. （オプション）個別のGitLab RailsとSidekiqノードでマルチサーバー環境を使用する場合は、SidekiqノードでKASを有効にします。

共通設定

各KASノードについて、/etc/gitlab/gitlab.rbのファイルを編集し、次の設定を追加します:

gitlab_kas_external_url 'wss://kas.gitlab.example.com/'

gitlab_kas['api_secret_key'] = '<32_bytes_long_base64_encoded_value>'
gitlab_kas['private_api_secret_key'] = '<32_bytes_long_base64_encoded_value>'

# private_api_listen_address examples, pick one:

gitlab_kas['private_api_listen_address'] = 'A.B.C.D:8155' # Listen on a particular IPv4. Each node must use its own unique IP.
# gitlab_kas['private_api_listen_address'] = '[A:B:C::D]:8155' # Listen on a particular IPv6. Each node must use its own unique IP.
# gitlab_kas['private_api_listen_address'] = 'kas-N.gitlab.example.com:8155' # Listen on all IPv4 and IPv6 interfaces that the DNS name resolves to. Each node must use its own unique domain.
# gitlab_kas['private_api_listen_address'] = ':8155' # Listen on all IPv4 and IPv6 interfaces.
# gitlab_kas['private_api_listen_address'] = '0.0.0.0:8155' # Listen on all IPv4 interfaces.
# gitlab_kas['private_api_listen_address'] = '[::]:8155' # Listen on all IPv6 interfaces.

# Uncomment below to enable KAS to KAS TLS communication
# gitlab_kas['private_api_certificate_file'] = '<path_to_kas_server_crt_file>'
# gitlab_kas['private_api_key_file'] = '<path_to_kas_server_certificate_key>'

gitlab_kas['env'] = {
  # 'OWN_PRIVATE_API_HOST' => '<server-name-from-cert>' # Add if you want to use TLS for KAS->KAS communication. This name is used to verify the TLS certificate host name instead of the host in the URL of the destination KAS.
  'SSL_CERT_DIR' => "/opt/gitlab/embedded/ssl/certs/",
}

gitlab_rails['gitlab_kas_external_url'] = 'wss://gitlab.example.com/-/kubernetes-agent/'
gitlab_rails['gitlab_kas_internal_url'] = 'grpc://kas.internal.gitlab.example.com'
gitlab_rails['gitlab_kas_external_k8s_proxy_url'] = 'https://gitlab.example.com/-/kubernetes-agent/k8s-proxy/'

Do not（設定しないでください）private_api_listen_address内部アドレス（以下など）をリッスンするようにします:

• localhost
• 127.0.0.1または::1のようなループバックIPアドレス
• UNIXソケット

他のKASノードはこれらのアドレスに到達できません。

単一ノード構成では、private_api_listen_addressを内部アドレスをリッスンするように設定できます。

オプション1 - 明示的な手動設定

各KASノードについて、/etc/gitlab/gitlab.rbのファイルを編集し、OWN_PRIVATE_API_URL環境変数を明示的に設定します:

gitlab_kas['env'] = {
  # OWN_PRIVATE_API_URL examples, pick one. Each node must use its own unique IP or DNS name.
  # Use grpcs:// when using TLS on the private API endpoint.

  'OWN_PRIVATE_API_URL' => 'grpc://A.B.C.D:8155' # IPv4
  # 'OWN_PRIVATE_API_URL' => 'grpcs://A.B.C.D:8155' # IPv4 + TLS
  # 'OWN_PRIVATE_API_URL' => 'grpc://[A:B:C::D]:8155' # IPv6
  # 'OWN_PRIVATE_API_URL' => 'grpc://kas-N-private-api.gitlab.example.com:8155' # DNS name
}

オプション2 - 自動CIDRベースの設定

たとえば、KASホストにIPアドレスとホスト名が動的に割り当てられている場合、OWN_PRIVATE_API_URL変数に正確なIPアドレスまたはホスト名を設定できない場合があります。

正確なIPアドレスまたはホスト名を設定できない場合は、1つ以上のCIDRに基づいて動的にOWN_PRIVATE_API_URLを構築するようにKASを設定するために、OWN_PRIVATE_API_CIDRを設定できます:

このアプローチにより、各KASノードは、CIDRが変更されない限り機能する静的な設定を使用できます。

各KASノードについて、/etc/gitlab/gitlab.rbのファイルを編集して、OWN_PRIVATE_API_URL URLを動的に構築します:

1. この変数をオフにするには、共通設定のOWN_PRIVATE_API_URLをコメントアウトします。
2. KASノードがリッスンするネットワークを指定するようにOWN_PRIVATE_API_CIDRを設定します。KASを起動すると、指定されたCIDRに一致するホストアドレスを選択することにより、使用するプライベートIPアドレスが決定されます。
3. 別のポートを使用するようにOWN_PRIVATE_API_PORTを設定します。デフォルトでは、KASはprivate_api_listen_addressパラメータからのポートを使用します。
4. プライベートAPIエンドポイントでTLSを使用する場合は、OWN_PRIVATE_API_SCHEME=grpcsを設定します。デフォルトでは、KASはgrpcスキームを使用します。

gitlab_kas['env'] = {
  # 'OWN_PRIVATE_API_CIDR' => '10.0.0.0/8', # IPv4 example
  # 'OWN_PRIVATE_API_CIDR' => '2001:db8:8a2e:370::7334/64', # IPv6 example
  # 'OWN_PRIVATE_API_CIDR' => '10.0.0.0/8,2001:db8:8a2e:370::7334/64', # multiple CIRDs example

  # 'OWN_PRIVATE_API_PORT' => '8155',
  # 'OWN_PRIVATE_API_SCHEME' => 'grpc',
}

オプション3 - リスナー設定に基づく自動設定

KASノードは、private_api_listen_networkおよびprivate_api_listen_address設定に基づいて、どのIPアドレスが利用可能かを判断できます:

• private_api_listen_addressが固定IPアドレスとポート番号（たとえば、ip:port）に設定されている場合、このIPアドレスを使用します。
• private_api_listen_addressにIPアドレスがない（たとえば、:8155）、または指定されていないIPアドレスがある（たとえば、[::]:8155または0.0.0.0:8155）場合、KASはすべての非ループバックおよび非リンクローカルIPアドレスをノードに割り当てます。IPv4およびIPv6アドレスは、private_api_listen_networkの値に基づいてフィルターされます。
• private_api_listen_addressがhostname:PORT（たとえば、kas-N-private-api.gitlab.example.com:8155）の場合、KASはドメイン名サービス名を解決し、すべてのIPアドレスをノードに割り当てます。このモードでは、KASは最初のIPアドレスでのみリッスンします（この動作はGo標準ライブラリによって定義されています）。IPv4およびIPv6アドレスは、private_api_listen_networkの値に基づいてフィルターされます。

すべてのIPアドレスでKASのプライベートAPIアドレスを公開する前に、このアクションが組織のセキュリティポリシーと矛盾しないことを確認してください。プライベートAPIエンドポイントには、すべてのリクエストに対して有効な認証トークンが必要です。

各KASノードについて、/etc/gitlab/gitlab.rbのファイルを編集します:

例1。すべてのIPv4およびIPv6インターフェースでリッスンします:

# gitlab_kas['private_api_listen_network'] = 'tcp' # this is the default value, no need to set it.
gitlab_kas['private_api_listen_address'] = ':8155' # Listen on all IPv4 and IPv6 interfaces

例2。すべてのIPv4インターフェースでリッスンします:

gitlab_kas['private_api_listen_network'] = 'tcp4'
gitlab_kas['private_api_listen_address'] = ':8155'

例3。すべてのIPv6インターフェースでリッスンします:

gitlab_kas['private_api_listen_network'] = 'tcp6'
gitlab_kas['private_api_listen_address'] = ':8155'

環境変数を使用して、OWN_PRIVATE_API_URLを構築するスキームとポートをオーバーライドできます:

gitlab_kas['env'] = {
  # 'OWN_PRIVATE_API_PORT' => '8155',
  # 'OWN_PRIVATE_API_SCHEME' => 'grpc',
}

エージェントサーバーノード設定

Footnotes（脚注）:

1. OWN_PRIVATE_API_URLまたはOWN_PRIVATE_API_SCHEMEがgrpcsで始まる場合、送信接続のTLSが有効になります。
2. たとえばwss://kas.gitlab.example.com/などです。
3. たとえばwss://gitlab.example.com/-/kubernetes-agent/などです。

GitLab Helmチャート

GitLab-KASチャートの使用方法を参照してください。

Kubernetes APIプロキシクッキー

KASは、次のいずれかを使用して、Kubernetes APIリクエストをKubernetes向けGitLabエージェントにプロキシします:

• CI/CD ジョブ。
• GitLabユーザー認証情報。

ユーザー認証情報で認証するには、RailsはGitLabフロントエンドのCookieを設定します。このCookieは_gitlab_kasと呼ばれ、_gitlab_sessionCookieのように、暗号化されたセッションIDが含まれています。ユーザーを認証および承認するには、すべてのリクエストで_gitlab_kasCookieをKASプロキシエンドポイントに送信する必要があります。

受信エージェントを有効にする

受容エージェントを使用すると、GitLabインスタンスへのネットワーク接続を確立できないがGitLabからは接続できるKubernetesクラスターと、GitLabを統合できます。

受信エージェントを有効にするには:

1. 左側のサイドバーの下部で、管理者を選択します。
2. 設定 > 一般を選択します。
3. GitLab Agent for Kubernetesを展開。
4. 受信モードを有効にするトグルをオンにします。

Kubernetes APIプロキシ応答ヘッダー許可リストを設定する

KASのKubernetes APIプロキシは、応答ヘッダーの許可リストを使用します。安全でよく知られているKubernetesおよびHTTPヘッダーは、デフォルトで許可されています。

許可されている応答ヘッダーのリストについては、応答ヘッダー許可リストを参照してください。

デフォルトの許可リストにない応答ヘッダーが必要な場合は、KAS設定に応答ヘッダーを追加できます。

許可されている追加の応答ヘッダーを追加するには:

agent:
  kubernetes_api:
    extra_allowed_response_headers:
      - 'X-My-Custom-Header-To-Allow'

応答ヘッダーの追加のサポートは、イシュー550614で追跡されています。

トラブルシューティング

Kubernetes用エージェントサーバーの使用中に問題が発生した場合は、次のコマンドを実行してサービスログを表示します:

kubectl logs -f -l=app=kas -n <YOUR-GITLAB-NAMESPACE>

Linuxパッケージインストールでは、/var/log/gitlab/gitlab-kas/にログがあります。

個々のエージェントに関する問題を解決することもできます。

設定ファイルが見つかりません

次のエラーメッセージが表示された場合:

time="2020-10-29T04:44:14Z" level=warning msg="Config: failed to fetch" agent_id=2 error="configuration file not found: \".gitlab/agents/test-agent/config.yaml\

次のいずれかのパスが正しくありません:

• エージェントが登録されたリポジトリ。
• エージェント設定ファイル。

この問題を解決するには、パスが正しいことを確認してください。

エラー: dial tcp <GITLAB_INTERNAL_IP>:443: connect: connection refused

GitLab Self-Managedを実行していて、:

• インスタンスがSSL終端プロキシの背後で実行されていない。
• インスタンス自体にHTTPSが設定されていないGitLabインスタンス。
• インスタンスのホスト名が、ローカルで内部IPアドレスに解決される。

エージェントサーバーがGitLab APIに接続しようとすると、次のエラーが発生する可能性があります:

{"level":"error","time":"2021-08-16T14:56:47.289Z","msg":"GetAgentInfo()","correlation_id":"01FD7QE35RXXXX8R47WZFBAXTN","grpc_service":"gitlab.agent.reverse_tunnel.rpc.ReverseTunnel","grpc_method":"Connect","error":"Get \"https://gitlab.example.com/api/v4/internal/kubernetes/agent_info\": dial tcp 172.17.0.4:443: connect: connection refused"}

Linuxパッケージインストールでこの問題を解決するには、/etc/gitlab/gitlab.rbに次のパラメータを設定します。gitlab.example.comをGitLabインスタンスのホスト名に置き換えます:

gitlab_kas['gitlab_address'] = 'http://gitlab.example.com'

エラー: x509: certificate signed by unknown authority

GitLab URLに到達しようとしたときにこのエラーが発生した場合、それはGitLab証明書を信頼していないことを意味します。

GitLabアプリケーションサーバーのKASログに同様のエラーが表示される場合があります:

{"level":"error","time":"2023-03-07T20:19:48.151Z","msg":"AgentInfo()","grpc_service":"gitlab.agent.agent_configuration.rpc.AgentConfiguration","grpc_method":"GetConfiguration","error":"Get \"https://gitlab.example.com/api/v4/internal/kubernetes/agent_info\": x509: certificate signed by unknown authority"}

このエラーを解決するには、内部認証局の公開証明書を/etc/gitlab/trusted-certsディレクトリにインストールします。

または、カスタムディレクトリから証明書を読み取りようにKASを設定することもできます。これを行うには、/etc/gitlab/gitlab.rbのファイルに次の設定を追加します:

gitlab_kas['env'] = {
   'SSL_CERT_DIR' => "/opt/gitlab/embedded/ssl/certs/"
 }

変更を適用するには、再構成します:

1. GitLabを再設定します:

sudo gitlab-ctl reconfigure

1. エージェントサーバーを再起動します:

gitlab-ctl restart gitlab-kas

エラー: GRPC::DeadlineExceeded in Clusters::Agents::NotifyGitPushWorker

このエラーは、クライアントがデフォルトのタイムアウト期間（5秒）内に応答を受信しない場合に発生する可能性があります。この問題を解決するには、/etc/gitlab/gitlab.rb設定ファイルを修正して、クライアントのタイムアウトを増やすことができます。

解決する手順

1. タイムアウト値を大きくするために、次の設定を追加または更新します:

gitlab_kas['client_timeout_seconds'] = "10"

1. GitLabを再設定して変更を適用します:

gitlab-ctl reconfigure

注

特定のニーズに合わせてタイムアウト値を調整できます。システムパフォーマンスに影響を与えずに問題が解決されることを確認するために、テストをお勧めします。

エラー: Blocked Kubernetes API proxy response header

KubernetesクラスターからKubernetes APIプロキシを介してユーザーに送信されたときにHTTP応答ヘッダーが失われた場合は、KASログまたはSentryインスタンスで次のエラーを確認してください:

Blocked Kubernetes API proxy response header. Please configure extra allowed headers for your instance in the KAS config with `extra_allowed_response_headers` and have a look at the troubleshooting guide at https://docs.gitlab.com/administration/clusters/kas/#troubleshooting.

このエラーは、応答ヘッダーが応答ヘッダー許可リストで定義されていないため、Kubernetes APIプロキシが応答ヘッダーをブロックしたことを意味します。

応答ヘッダーの追加の詳細については、応答ヘッダー許可リストを設定するを参照してください。

応答ヘッダーの追加のサポートは、イシュー550614で追跡されています。