Kubernetes用エージェントのインストール
KubernetesクラスターをGitLabに接続するには、クラスターにエージェントをインストールする必要があります。
前提条件
クラスターにエージェントをインストールする前に、以下のものが必要です：
- 既存のKubernetesクラスター。クラスターをお持ちでない場合は、以下のようなクラウドプロバイダーで作成できます：
- セルフマネージドGitLabインスタンスでは、GitLab管理者がエージェントサーバーをセットアップする必要があります。その後、デフォルトで
wss://gitlab.example.com/-/kubernetes-agent/。GitLab.comでは、エージェントサーバはwss://kas.gitlab.com。
インストール手順
エージェントをクラスターにインストールします：
- エージェント設定ファイルを作成します。
- エージェントをGitLabに登録します。
- エージェントをクラスターにインストールします。
このプロセスのGitLab 14.2ウォークスルーをご覧ください。
エージェント設定ファイルの作成
設定について、エージェントはGitLabプロジェクト内のYAMLファイルを使用します。以下の場合、このファイルを作成する必要があります：
- GitOpsワークフローを使用している場合。
- GitLab CI/CDワークフローを使用していて、エージェントを使用するために別のプロジェクトを承認したい場合。
- 特定のプロジェクトやグループのメンバーにKubernetesへのアクセスを許可したい場合。
エージェント設定ファイルを作成します：
-
エージェントの名前を決めます。エージェント名は、RFC 1123のDNSラベル標準に従います。この名前は
- プロジェクト内で一意であること。
- 最大63文字のコンテナ。
- 小文字の英数字のみ、または
-。 - 英数字で始めてください。
- 英数字で終わります。
-
リポジトリのデフォルトブランチで、ルートにエージェント設定ファイルを作成します：
.gitlab/agents/<agent-name>/config.yaml
今は空白にしておいて、後で設定することもできます。
GitLab にエージェントを登録します。
フラグ: GitLab 14.10では、certificate_based_clusters というフラグにより、アクションメニューが証明書ではなくエージェントにフォーカスするように変更されました。このフラグはGitLab.comで有効化され、自己管理されます。
前提条件：
- GitLab CI/CD ワークフローでは、GitLab CI/CD が無効になっていないことを確認してください。
エージェントをクラスターにインストールする前に、エージェントを登録する必要があります。エージェントを登録するには
- 左サイドバーで、[検索]を選択するか、[プロジェクト]に移動して、プロジェクトを見つけます。エージェント設定ファイルがある場合、それはこのプロジェクトになければなりません。クラスタマニフェストファイルもこのプロジェクトにある必要があります。
- オペレーション > Kubernetesクラスターを選択します。
-
クラスター（エージェント）を接続]を選択します。
- CI/CDのデフォルトで設定を作成する場合は、名前を入力します。
- すでにエージェント設定ファイルがある場合は、リストから選択します。
- エージェントの登録を選択します。
-
GitLabがエージェントのアクセストークンを生成します。エージェントをクラスターにインストールするにはこのトークンが必要です。
エージェントのアクセストークンをセキュアに保存します。悪質な行為者はこのトークンを使って、エージェントの設定プロジェクトのソースコードにアクセスしたり、GitLabインスタンス上の公開プロジェクトのソースコードにアクセスしたり、あるいは非常に特殊な条件下ではKubernetesマニフェストを取得したりすることができます。 - Recommended installation methodの下にあるコマンドをコピーしてください。ワンライナーでエージェントをクラスターにインストールするときに必要です。
クラスターへのエージェントのインストール
GitLab 14.10から導入されたGitLabでは、Helmを使ってエージェントをインストールすることを推奨しています。
クラスターをGitLabに接続するには、登録済みのエージェントをクラスターにインストールします。以下のどちらかを行います：
- Helmを使ってエージェントをインストールします。
- または、高度なインストール方法に従ってください。
どれを選べばよいかわからない場合は、Helmから始めることをお勧めします。
Helmによるエージェントのインストール
cluster-admin 権限でエージェントのサービスアカウントを設定します。本番システムではこれを使用しないでください。本番システムにデプロイするには、Helmインストールのカスタマイズの説明に従って、デプロイに必要な最小限の権限を持つサービスアカウントを作成し、インストール時に指定してください。Helmを使用してエージェントをクラスターにインストールするには、以下の手順に従います：
- Helmをインストールします。
- コンピュータでターミナルを開き、クラスターに接続します。
- エージェントをGitLabに登録したときにコピーしたコマンドを実行します。
- オプションです。Helm インストールをカスタマイズします。本番システムにエージェントをインストールする場合は、Helmインストールをカスタマイズしてサービスアカウントの権限を制限する必要があります。権限を制限してKubernetes用のGitLabエージェントをデプロイする方法」を参照してください。
Helm インストールのカスタマイズ
デフォルトでは、HelmのインストールコマンドはGitLabによって生成されます：
- デプロイ用の名前空間
gitlab-agentを作成します (--namespace gitlab-agent)。--create-namespaceフラグを省略することで、名前空間の作成をスキップできます。 - エージェントにサービスアカウントを設定し、
cluster-adminロールを割り当てます。できます：-
helm installコマンドに--set serviceAccount.create=falseを追加することで、サービスアカウントの作成をスキップします。この場合、serviceAccount.nameを既存のサービスアカウントに設定する必要があります。 -
helm installコマンドに--set rbac.useExistingRole <your role name>を追加して、サービスアカウントに割り当てられたロールをカスタマイズします。この場合、サービスアカウントで使用できる権限を制限したロールを事前に作成しておく必要があります。 -
helm installコマンドに--set rbac.create=falseを追加することで、ロールの割り当てを完全にスキップします。この場合、ClusterRoleBindingを手動で作成する必要があります。
-
- エージェントのアクセストークン用の
Secretリソースを作成します。代わりにトークン付きの自分の秘密を持ってくるには、トークン (--set token=...) を省略し、代わりに--set config.secretName=<your secret name>を使用します。 -
agentkポッド用のDeploymentリソースを作成します。
利用可能なカスタマイズの全リストを見るには、Helmチャートのデフォルト値ファイルを参照してください。
KAS が自己署名証明書の後ろにある場合のエージェントの使用
KASが自己署名証明書の後ろにある場合、config.caCert の値を証明書に設定できます。例えば
helm upgrade --install gitlab-agent gitlab/gitlab-agent \
--set-file config.caCert=my-custom-ca.pem
この例では、my-custom-ca.pem は KAS が使用する CA 証明書を含むローカルファイルへのパスです。証明書は自動的に設定マップに保存され、agentk ポッドにマウントされます。
KASがGitLabのChartと一緒にインストールされ、Chartが自動生成された自己署名ワイルドカード証明書を提供するように設定されている場合は、RELEASE-wildcard-tls-ca secretからCA証明書を抽出することができます。
HTTP プロキシの後ろでエージェントを使う
GitLab 15.0から導入されたGitLabエージェントのHelmチャートは環境変数の設定をサポートしています。
Helmチャートを使うときにHTTPプロキシを設定するには、環境変数HTTP_PROXY,HTTPS_PROXY,NO_PROXY を使うことができます。大文字でも小文字でも構いません。
これらの変数は、name とvalue をキーとするオブジェクトのリストとして、extraEnv の値を使用して設定できます。例えば、環境変数HTTPS_PROXY のみを値https://example.com/proxyに設定するには、次のように実行します：
helm upgrade --install gitlab-agent gitlab/gitlab-agent \
--set extraEnv[0].name=HTTPS_PROXY \
--set extraEnv[0].value=https://example.com/proxy \
...
HTTP_PROXY またはHTTPS_PROXY 環境変数が設定され、ドメインDNSが解決できない場合、DNSリバインド保護は無効になります。高度なインストール方法
GitLabはエージェント用のKPTパッケージも提供しています。この方法はより柔軟性がありますが、上級ユーザーにのみお勧めします。
エージェントの設定
エージェントを設定するには、config.yaml ファイルに内容を追加します：
- GitOpsワークフローについては、設定リファレンスを参照してください。
- GitLab CI/CDワークフローでは、エージェントにプロジェクトへのアクセス権限を付与します。それから
kubectlコマンドを.gitlab-ci.ymlファイルに追加します。
クラスターに複数のエージェントをインストールします。
クラスタに2つ目のエージェントをインストールするには、2回目の前の手順を実行します。クラスター内でのリソース名の衝突を避けるには、次のいずれかを実行する必要があります：
-
エージェントに別のリリース名を使用します。たとえば、
second-gitlab-agent：helm upgrade --install second-gitlab-agent gitlab/gitlab-agent ... -
または、エージェントを別の名前空間にインストールします。例えば、
different-namespace：helm upgrade --install gitlab-agent gitlab/gitlab-agent \ --namespace different-namespace \ ...
プロジェクト例
以下のサンプルプロジェクトは、エージェントを使い始めるのに役立ちます。
- 最小限のマニフェストを持つ設定リポジトリ
- 個別のアプリケーションとマニフェストリポジトリの例
- CI/CD ワークフローを使用する自動 DevOps 設定
- CI/CD ワークフローを使用するクラスター管理プロジェクトテンプレートの例
更新とバージョンの互換性
GitLab 14.8で導入されたGitLabは、エージェントの一覧ページでクラスターにインストールされているエージェントのバージョンを更新するよう警告します。
最高の使い心地を得るためには、クラスターにインストールされているエージェントのバージョンがGitLabのメジャーバージョンとマイナーバージョンに一致している必要があります。以前のマイナーバージョンもサポートされています。例えば、GitLabのバージョンがv14.9.4（メジャーバージョン14、マイナーバージョン9）の場合、エージェントのバージョンはv14.9.0とv14.9.1が理想的ですが、エージェントのv14.8.xバージョンもサポートされています。GitLabエージェントのリリースページをご覧ください。
エージェントバージョンの更新
エージェントを最新バージョンに更新するには、以下を実行します：
helm repo update
helm upgrade --install gitlab-agent gitlab/gitlab-agent \
--namespace gitlab-agent \
--reuse-values
特定のバージョンを設定するには、image.tag の値を上書きします。例えば、バージョンv14.9.1をインストールするには、以下を実行します：
helm upgrade gitlab-agent gitlab/gitlab-agent \
--namespace gitlab-agent \
--reuse-values \
--set image.tag=v14.9.1
HelmチャートはKubernetes用エージェントとは別に更新されるため、エージェントの最新バージョンに遅れることがあります。helm repo update を実行し、イメージタグを指定しない場合、エージェントはチャートで指定されたバージョンを実行します。
Kubernetes用エージェントの最新リリースを使用するには、最新のエージェントイメージに一致するようにイメージタグを設定します。
エージェントのアンインストール
Helm を使用してエージェントをインストールした場合、Helm を使用してアンインストールすることもできます。たとえば、リリースと名前空間が両方ともgitlab-agentという名前である場合、次のコマンドを使用してエージェントをアンインストールできます：
helm uninstall gitlab-agent \
--namespace gitlab-agent