正式なドキュメントは英語版であり、この日本語訳はAI支援翻訳により作成された参考用のものです。日本語訳の一部の内容は人間によるレビューがまだ行われていないため、翻訳のタイミングにより英語版との間に差異が生じることがあります。最新かつ正確な情報については、英語版をご参照ください。

チュートリアル: Kubernetes向けGitLabエージェントをセットアップする

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

ワークスペースをサポートするようにKubernetes向けGitLabエージェントを設定する前に、このチュートリアルで設定手順を完了する必要があります。チュートリアルを完了したら、Kubernetes向けGitLabエージェントの設定を使用してエージェントを設定します。

はじめる前

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

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

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

%%{init: {  "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.

    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コントローラーをインストールして、外部トラフィックをワークスペースにルーティングします。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エージェントをインストールする

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

  1. Kubernetes向けエージェントのインストールのいずれかのインストールオプションを完了してください。
  2. 設定したagentNameをメモします。ワークスペース用にエージェントを設定する際に必要です。

GitLab Relay (KAS) をインストールします

GitLab Relay (KAS) は、クラスター内のエージェントと通信するコンポーネントです。

  • GitLab.comでは、GitLab Relay (KAS) はデフォルトでwss://kas.gitlab.comで利用できます。
  • GitLab Self-Managedでは、管理者がGitLab Relay (KAS) を設定する必要があります。その後、wss://gitlab.example.com/-/kubernetes-agent/で利用可能です。

Kubernetes向けGitLabエージェントを設定する

エージェントプロジェクトで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エージェントは1つのプロジェクトで設定されますが、他のプロジェクトワークスペースで使用できます。各プロジェクトに個別のエージェントは必要ありません。

設定済みのエージェントは、グループでグループでエージェントを許可するまで表示されません。

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

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

必要なエージェントは1つだけです。同じエージェントを使用するグループ内のすべてのプロジェクトからワークスペースを作成できます。

グループで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で利用できます。

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

手動で証明書を生成するには:

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

    brew install certbot

  2. Let’s Encrypt証明書をACME DNSで生成し、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

証明書の有効期限が切れたら、更新する必要があります。例えば、Let’s Encrypt証明書は3ヶ月後に有効期限が切れます。証明書を自動的に更新するには、cert-managerを参照してください。

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.25 \
  --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>"