チュートリアル: GitLab Agent for Kubernetesをセットアップする

このチュートリアルでは、次の方法について説明します:

• Kubernetes向けGitLabエージェントを設定して、ユーザーがプロジェクトでワークスペースを作成および管理できるようにします。
• 認証と認証を行うためにGitLabワークスペースプロキシを設定します。ワークスペースをクラスターに作成します。

はじめる前

このチュートリアルを開始する前に、以下が必要です:

• GitLabインスタンスへの管理者アクセス権、またはグループのオーナーロール。
• 実行中のKubernetesクラスター。
• ローカルマシンのhelm 3.11.0以降およびkubectl。
• DNSプロバイダーでワイルドカードドメインを設定するアクセス権。たとえば、*.workspaces.example.devはワークスペースアクセスに必要です。

このチュートリアルでは、次の階層が使用されます:

%%{init: { "theme": "neutral", "fontFamily": "GitLab Sans" }}%%
graph TD
    accTitle: Hierarchy structure for GitLab workspaces
    accDescr: Workspace projects inherit agent access through the group hierarchy with agents connected to separate agent projects.

    classDef active fill:lightgreen, stroke:#green, color:green, stroke-width:1px;

    topGroup[Top-level group]
    subGroup[Subgroup]
    workspaceProject[Workspace project]
    agentProject[Agent project]
    workspaceAgent[Workspace agent]

    topGroup --> subGroup

    subGroup --> workspaceProject
    subGroup --> agentProject
    agentProject -.- workspaceAgent

    class workspaceProject active;

Ingressコントローラーをインストールする

外部トラフィックをワークスペースにルーティングするために、Kubernetesクラスターに任意のIngress controllerをインストールします。Ingressコントローラーは、WebSocketsをサポートしている必要があります。次の例では、Ingress NGINXコントローラーを使用します。

1. Kubernetesクラスターに、Ingressコントローラーをインストールします。

   helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
   helm repo update
   helm install ingress-nginx ingress-nginx/ingress-nginx \
     --namespace gitlab-ingress-controller \
     --create-namespace

2. ロードバランサーの外部IPアドレスを取得します。これは、DNSレコードを更新するときに必要になります。

   kubectl get svc -n gitlab-ingress-controller ingress-nginx-controller

Kubernetes向けGitLab agentをインストールします

クラスターをGitLabに接続するために、KubernetesクラスターにKubernetes向けGitLabエージェントをインストールします:

1. Kubernetes用エージェントのインストールで、いずれかのインストールオプションを完了します。
2. 設定したagentNameをメモしておきます。これは、ワークスペースのエージェントを設定するときに必要になります。

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

Kubernetes（KAS）向けGitLabエージェントサーバーは、クラスター内のエージェントと通信するコンポーネントです。

• GitLab.comでは、エージェントサーバーはwss://kas.gitlab.comがデフォルトで利用できます。
• GitLabセルフマネージドでは、管理者がKubernetesエージェントサーバー（KAS）をセットアップする必要があります。その後、wss://gitlab.example.com/-/kubernetes-agent/で使用できるようになります。

Kubernetes向けGitLab agentを設定します

エージェントプロジェクトでremote_developmentモジュールを設定するには:

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。

2. プロジェクトで、.gitlab/agents/<agentName>/config.yamlファイルを作成します。agentNameは、ワークスペースインフラストラクチャをセットアップしたときに構成したエージェントの名前です。

3. config.yamlで、ワークスペース設定に次の設定を使用します:

   remote_development:
     enabled: true
     dns_zone: "<workspaces.example.dev>" # DNS zone of the URL where workspaces are available

設定オプションの完全なリストについては、ワークスペースの設定リファレンスを参照してください。

グループでKubernetes向けGitLabエージェントを許可する

グループでエージェントを許可すると、グループ、そのサブグループ、およびそれらのグループ内のすべてのプロジェクトがそのエージェントを使用できるようになります。

グループでKubernetes向けGitLabエージェントを許可し、そのグループ内のすべてのプロジェクトで使用できるようにするには:

1. 左側のサイドバーで、検索または移動先を選択して、グループを見つけます。
2. 左側のサイドバーで、設定> ワークスペースを選択します。
3. グループエージェントセクションで、すべてのエージェントタブを選択します。
4. Kubernetes向けGitLabエージェントの場合は、許可を選択します。
5. 確認ダイアログで、エージェントを許可するを選択します。

ワークスペースの権限を付与する

ワークスペースおよびエージェントプロジェクトの少なくともデベロッパーロールを持つユーザーに、ワークスペースを作成および管理するために必要な権限を付与します。次のことができます:

• プロジェクトにユーザーを追加する
• グループにユーザーを追加する

TLS認証局を生成する

各ワークスペースが独自のサブドメインを取得するため、ワークスペースアクセスにはワイルドカードドメインが必要です。次のTLS認証局を生成する必要があります:

• ドメインgitlab-workspaces-proxyがリッスンする（GITLAB_WORKSPACES_PROXY_DOMAIN）。
• ワークスペースが利用可能なワイルドカードドメイン（GITLAB_WORKSPACES_WILDCARD_DOMAIN）。

たとえば、ベースドメインがworkspaces.example.devの場合:

• GITLAB_WORKSPACES_PROXY_DOMAINはworkspaces.example.devです。
• GITLAB_WORKSPACES_WILDCARD_DOMAINは*.workspaces.example.devです。
• 個々のワークスペースは、workspace-1.workspaces.example.devのようなURLで利用できます。

任意の認証局から認証局を生成できます。cert-managerがKubernetesクラスター用に設定されている場合は、それを使用してTLS認証局を自動的に作成および更新できます。

認証局を手動で生成するには:

1. HTTPSを有効にするには、Certbotをインストールします:

   brew install certbot

2. ACME DNSを使用してLet’s Encrypt認証局を生成し、DNSプロバイダーにTXTレコードを作成します:

   export EMAIL="YOUR_EMAIL@example.dev"
   export GITLAB_WORKSPACES_PROXY_DOMAIN="workspaces.example.dev"
   export GITLAB_WORKSPACES_WILDCARD_DOMAIN="*.workspaces.example.dev"
   
   certbot -d "${GITLAB_WORKSPACES_PROXY_DOMAIN}" \
     -m "${EMAIL}" \
     --config-dir ~/.certbot/config \
     --logs-dir ~/.certbot/logs \
     --work-dir ~/.certbot/work \
     --manual \
     --preferred-challenges dns certonly
   
   certbot -d "${GITLAB_WORKSPACES_WILDCARD_DOMAIN}" \
     -m "${EMAIL}" \
     --config-dir ~/.certbot/config \
     --logs-dir ~/.certbot/logs \
     --work-dir ~/.certbot/work \
     --manual \
     --preferred-challenges dns certonly

3. 次の環境変数を、出力からの認証局ディレクトリとともに設定します:

   export WORKSPACES_DOMAIN_CERT="${HOME}/.certbot/config/live/${GITLAB_WORKSPACES_PROXY_DOMAIN}/fullchain.pem"
   export WORKSPACES_DOMAIN_KEY="${HOME}/.certbot/config/live/${GITLAB_WORKSPACES_PROXY_DOMAIN}/privkey.pem"
   export WILDCARD_DOMAIN_CERT="${HOME}/.certbot/config/live/${GITLAB_WORKSPACES_PROXY_DOMAIN}-0001/fullchain.pem"
   export WILDCARD_DOMAIN_KEY="${HOME}/.certbot/config/live/${GITLAB_WORKSPACES_PROXY_DOMAIN}-0001/privkey.pem"

   環境によっては、certbotコマンドが認証局とキーを別のパスに保存する場合があります。正確なパスを取得するには、次を実行します:

   certbot certificates \
     --config-dir ~/.certbot/config \
     --logs-dir ~/.certbot/logs \
     --work-dir ~/.certbot/work

GitLab OAuthアプリケーションを登録する

GitLabインスタンスにOAuthアプリケーションを登録するには:

1. GitLabでOAuthアプリケーションを作成します。以下を作成できます:

   • ユーザーが所有するアプリケーション
   • グループが所有するアプリケーション
   • 管理者エリアからのインスタンス全体のアプリケーション

2. リダイレクトURIをhttps://${GITLAB_WORKSPACES_PROXY_DOMAIN}/auth/callbackに設定します。

3. 非公開チェックボックスが選択されていることを確認してください。これは、デフォルトで選択されているはずです。

4. インスタンス全体のアプリケーションを作成する場合は、信用済みチェックボックスも選択してください。

5. スコープをapi、read_user、openid、およびprofileに設定します。

6. 設定値をエクスポートします:

   export GITLAB_URL="https://gitlab.com"
   export CLIENT_ID="your_application_id"
   export CLIENT_SECRET="your_application_secret"
   export REDIRECT_URI="https://${GITLAB_WORKSPACES_PROXY_DOMAIN}/auth/callback"
   export SIGNING_KEY="make_up_a_random_key_consisting_of_letters_numbers_and_special_chars"

7. クライアントIDと生成されたシークレットを安全に保存します（たとえば、1Passwordなど）。

SSHホストキーを生成する

RSAキーを生成するには:

ssh-keygen -f ssh-host-key -N '' -t rsa
export SSH_HOST_KEY=$(pwd)/ssh-host-key

別の方法として、ECDSAキーを生成することもできます。

Kubernetes Secretsを作成する

Kubernetes Secretsを作成するには:

kubectl create namespace gitlab-workspaces

kubectl create secret generic gitlab-workspaces-proxy-config \
  --namespace="gitlab-workspaces" \
  --from-literal="auth.client_id=${CLIENT_ID}" \
  --from-literal="auth.client_secret=${CLIENT_SECRET}" \
  --from-literal="auth.host=${GITLAB_URL}" \
  --from-literal="auth.redirect_uri=${REDIRECT_URI}" \
  --from-literal="auth.signing_key=${SIGNING_KEY}" \
  --from-literal="ssh.host_key=$(cat ${SSH_HOST_KEY})"

kubectl create secret tls gitlab-workspace-proxy-tls \
  --namespace="gitlab-workspaces" \
  --cert="${WORKSPACES_DOMAIN_CERT}" \
  --key="${WORKSPACES_DOMAIN_KEY}"

kubectl create secret tls gitlab-workspace-proxy-wildcard-tls \
  --namespace="gitlab-workspaces" \
  --cert="${WILDCARD_DOMAIN_CERT}" \
  --key="${WILDCARD_DOMAIN_KEY}"

GitLabワークスペースプロキシHelmチャートをインストールする

GitLabワークスペースプロキシのHelmチャートをインストールするには:

1. helmリポジトリを追加します:

   helm repo add gitlab-workspaces-proxy \
     https://gitlab.com/api/v4/projects/gitlab-org%2fworkspaces%2fgitlab-workspaces-proxy/packages/helm/devel

   Helmチャート0.1.13以前の場合は、次のコマンドを使用します:

   helm repo add gitlab-workspaces-proxy \
     https://gitlab.com/api/v4/projects/gitlab-org%2fremote-development%2fgitlab-workspaces-proxy/packages/helm/devel

2. チャートをインストールしてアップグレードします:

   チャートのバージョン0.1.22以前には、コマンドライン引数を介して機密情報を公開するセキュリティ脆弱性が含まれています。詳細については、脆弱性を参照してください。

   チャートのバージョン0.1.20以前には、ワイルドカードドメインにCookieを設定するセキュリティ脆弱性も含まれています。詳細については、脆弱性の修正を参照してください。

   両方の脆弱性に対処するには、チャートのバージョン0.1.23以降にアップグレードする必要があります。

   チャートのバージョン0.1.16以前は、Helmチャートのインストールによってシークレットが自動的に作成されていました。バージョン0.1.16以前からアップグレードする場合は、アップグレードコマンドを実行する前に、必要なKubernetes Secretsを作成します。

   helm repo update
   
   helm upgrade --install gitlab-workspaces-proxy \
     gitlab-workspaces-proxy/gitlab-workspaces-proxy \
     --version=0.1.23 \
     --namespace="gitlab-workspaces" \
     --set="ingress.enabled=true" \
     --set="ingress.hosts[0].host=${GITLAB_WORKSPACES_PROXY_DOMAIN}" \
     --set="ingress.hosts[0].paths[0].path=/" \
     --set="ingress.hosts[0].paths[0].pathType=ImplementationSpecific" \
     --set="ingress.hosts[1].host=${GITLAB_WORKSPACES_WILDCARD_DOMAIN}" \
     --set="ingress.hosts[1].paths[0].path=/" \
     --set="ingress.hosts[1].paths[0].pathType=ImplementationSpecific" \
     --set="ingress.tls[0].hosts[0]=${GITLAB_WORKSPACES_PROXY_DOMAIN}" \
     --set="ingress.tls[0].secretName=gitlab-workspace-proxy-tls" \
     --set="ingress.tls[1].hosts[0]=${GITLAB_WORKSPACES_WILDCARD_DOMAIN}" \
     --set="ingress.tls[1].secretName=gitlab-workspace-proxy-wildcard-tls" \
     --set="ingress.className=nginx"

   別のIngressクラスを使用している場合は、ingress.classNameパラメータを変更します。

設定を確認する

1. gitlab-workspacesネームスペースのIngress設定を確認します:

   kubectl -n gitlab-workspaces get ingress

2. ポッドが実行されていることを確認します:

   kubectl -n gitlab-workspaces get pods

DNSレコードを更新する

DNSレコードを更新するには:

1. ${GITLAB_WORKSPACES_PROXY_DOMAIN}と${GITLAB_WORKSPACES_WILDCARD_DOMAIN}を、Ingressコントローラーによって公開されているロードバランサーの外部IPアドレスにポイントします。

2. gitlab-workspaces-proxyにアクセスできるかどうかを確認します:

   curl --verbose --location ${GITLAB_WORKSPACES_PROXY_DOMAIN}

   このコマンドは、ワークスペースを作成するまで400 Bad Requestエラーを返します。

3. 別のターミナルから、プロキシログを確認します:

   kubectl -n gitlab-workspaces logs -f -l app.kubernetes.io/name=gitlab-workspaces-proxy

   このコマンドは、ワークスペースを作成するまでcould not find upstream workspace upstream not foundエラーを返します。

Kubernetes向けGitLabエージェントの設定を更新します

プロキシのHelmチャートをgitlab-workspaces以外のネームスペースにデプロイする場合は、Kubernetes設定向けGitLabエージェントを更新します:

remote_development:
  gitlab_workspaces_proxy:
    namespace: "<custom-gitlab-workspaces-proxy-namespace>"

関連トピック

• ワークスペースを設定する
• GitLab Agent for Kubernetesの設定