Kubernetesクラスタ

概要

GitLabプロジェクトのKubernetesインテグレーションを使用すると、次のことができます：

Kubernetesクラスターは、プロジェクトレベルでのインテグレーション以外にも、グループレベルやGitLabインスタンスレベルでのインテグレーションも可能です。

セットアップ

対応クラスターのバージョン

GitLabは、本番環境で利用可能なKubernetesのマイナーバージョンを常時2つ以上サポートすることをお約束します。 サポートするバージョンを定期的にレビューし、特定のバージョンのサポートを終了する前に4ヶ月の非推奨期間を設けています。 サポートするバージョンの範囲は、以下の評価に基づいています：

現在、GitLabは以下のKubernetesバージョンをサポートしています：

  • 1.16
  • 1.15
  • 1.14
  • 1.13（非推奨、2020年11月22日でサポート終了）
  • 1.12（非推奨、2020年9月22日でサポート終了）
注意：GitLabの機能の中には、ここで提供された範囲外のバージョンをサポートするものもあります。

クラスターの追加と削除

方法の詳細については、Kubernetesクラスターの追加と削除を参照してください：

  • GitLab の UI を使用して、Google Cloud Platform(GCP) または Amazon Elastic Kubernetes Service(EKS) でクラスターを作成します。
  • どのKubernetesプラットフォームからでも、既存のクラスターにインテグレーションを追加できます。

複数のKubernetesクラスター

プロジェクトには複数のKubernetesクラスターを関連付けることができます。 そうすることで、開発環境、ステージング環境、本番環境など、環境ごとに異なるクラスターを持つことができます。

初回と同じように別のクラスターを追加し、新しいクラスターを他のクラスターと区別できるように環境スコープを設定してください。

環境スコープの設定

プロジェクトに複数のKubernetesクラスタを追加する場合は、環境スコープで区別する必要があります。 環境スコープは、環境固有の変数が機能するのと同様に、クラスタを環境に関連付けます。

デフォルトの環境スコープは*です。これは環境に関係なく、すべてのジョブがそのクラスターを使用することを意味します。各スコープはプロジェクト内の1つのクラスターでのみ使用でき、そうでない場合は検証エラーが発生します。 また、環境キーワードが設定されていないジョブはどのクラスターにもアクセスできません。

例えば、プロジェクトに以下のようなKubernetesクラスターが存在するとします：

クラスター 環境範囲
開発者 *
製造 production

そして、.gitlab-ci.ymlに以下の環境が設定されています： 

stages:
  - test
  - deploy

test:
  stage: test
  script: sh test

deploy to staging:
  stage: deploy
  script: make deploy
  environment:
    name: staging
    url: https://staging.example.com/

deploy to production:
  stage: deploy
  script: make deploy
  environment:
    name: production
    url: https://example.com/

結果はこうなります：

  • 開発クラスターの詳細は、deploy to stagingジョブで確認できます。
  • 本番クラスターの詳細は、deploy to productionジョブで確認できます。
  • test ジョブでは環境を定義していないため、クラスターの詳細は利用できません。

Kubernetesクラスターの設定

KubernetesクラスターをGitLabに追加した後、GitLabでKubernetesクラスターを設定するための重要な考慮事項をカバーするこのセクションをお読みください。

セキュリティへの影響

重要:クラスタ全体のセキュリティは、開発者が信頼されるモデルに基づいています。したがって、信頼されたユーザのみがクラスタを制御できるようにする必要があります。

デフォルトのクラスター構成では、コンテナ化されたアプリケーションの構築とデプロイを成功させるために必要な幅広い機能セットへのアクセスが許可されます。 クラスター上で実行されるすべてのアプリケーションで同じ認証情報が使用されることに留意してください。

GitLabが管理するクラスター

GitLabにクラスターを管理させることもできます。 GitLabにクラスターを管理させると、プロジェクト用のリソースが自動的に作成されます。 作成されるリソースの詳細については、アクセスコントロールのセクションを参照してください。

独自のクラスターを管理することを選択した場合、プロジェクト固有のリソースは自動的に作成されません。Auto DevOpsを使用している場合は、デプロイジョブで使用されるKUBE_NAMESPACE デプロイ変数を明示的に指定する必要があります。そうしないと、名前空間が作成されます。

重要な注意事項

GitLabとクラスターでは以下のことに注意してください：

  • クラスターにアプリケーションをインストールする場合、GitLabはこれらの実行に必要なリソースを作成します。
  • 名前空間やサービスアカウントなど、GitLabによって作成されたリソースを手動で管理すると、予期しないエラーが発生することがあるので注意してください。 このような場合は、クラスターのキャッシュをクリアしてみてください。

クラスター・キャッシュのクリア

GitLab 12.6 で導入されました。

GitLab にクラスターの管理を任せることにした場合、GitLab はプロジェクト用に作成した名前空間とサービスアカウントのキャッシュを保存します。 クラスター内のこれらのリソースを手動で変更すると、このキャッシュがクラスターと同期しなくなり、デプロイジョブが失敗することがあります。

キャッシュをクリアするには

  1. プロジェクトのオペレーション>Kubernetesページに移動し、クラスターを選択します。
  2. 詳細設定セクションを展開します。
  3. Clearclustercache］をクリックします。

ベースドメイン

GitLab 11.8 で導入されました。

注意:GitLab Serverlessを使用する場合、クラスター設定でベースドメインを指定する必要はありません。 その場合のドメインは、Knativeのインストールの一部として指定されます。アプリケーションのインストールを参照してください。

ベースドメインを指定すると、環境変数としてKUBE_INGRESS_BASE_DOMAIN が自動的に設定されます。Auto DevOps を使用している場合、このドメインは異なるステージで使用されます。 たとえば、Auto Review Apps や Auto Deploy などです。

ドメインは、IngressのIPアドレスにワイルドカードDNSが設定されている必要があります。 Ingressがインストールされた後（アプリケーションのインストールを参照）、次のことができます：

  • ドメインプロバイダでIngress IPアドレスを指すA レコードを作成します。
  • nip.ioやxip.ioなどのサービスを利用してワイルドカードDNSアドレスを入力します。例えば、192.168.1.1.xip.io.

アプリケーションのインストール

GitLabでは、Helm、GitLab Runner、Ingress、Prometheusなどのアプリケーションをプロジェクトレベルのクラスターにインストールして管理することができます。 プロジェクトクラスターへのアプリケーションのインストール、アップグレード、アンインストール、トラブルシューティングの詳細については、GitLab Managed Appsを参照してください。

Auto DevOps

Auto DevOpsは、アプリケーションの検出、ビルド、テスト、デプロイ、監視を自動的に行います。

Auto DevOps（オートデプロイ、オートレビューアプリ、オートモニタリング）をフル活用するには、Kubernetesプロジェクトインテグレーションを有効にする必要があります。

Auto DevOpsについてもっと読む

注KubernetesクラスターはAuto DevOpsなしで使用できます。

Kubernetesクラスターへのデプロイ

Kubernetesクラスターをデプロイジョブのデスティネーションにすることができます。

  • クラスターはGitLabとインテグレーションされており、特別なデプロイ変数がジョブで利用できるようになり、設定は不要です。kubectl やhelmなどのツールを使って、ジョブからすぐにクラスターとのやり取りを始めることができます。
  • GitLabのクラスター・インテグレーションを使わない場合でも、クラスターにデプロイすることはできます。 しかし、ジョブからクラスターとやり取りする前に、環境変数を使ってKubernetesツールを自分で設定する必要があります。

デプロイ変数

Kubernetesクラスタインテグレーションは、GitLab CI/CDビルド環境において以下のデプロイ変数を公開します。

変数 説明
KUBE_URL API URL に等しいです。
KUBE_TOKEN 環境サービスアカウントのKubernetesトークン。
KUBE_NAMESPACE プロジェクトのデプロイサービスアカウントに関連付けられた名前空間。<project_name>-<project_id>-<environment>の形式。 GitLabが管理するクラスターの場合、一致する名前空間はクラスター内のGitLabによって自動的に作成されます。
KUBE_CA_PEM_FILE PEM データを含むファイルへのパス。 カスタム CA バンドルが指定された場合のみ。
KUBE_CA_PEM (非推奨） 生の PEM デー タ 。 カ ス タ ム CA バ ン ド ルが指定 さ れてい る 場合のみ。
KUBECONFIG このデプロイ用のkubeconfig を含むファイルへのパス。指定すると CA バンドルが埋め込まれます。このコンフィグもKUBE_TOKEN で定義されているのと同じトークンを埋め込むので、この変数だけが必要になる可能性が高いです。この変数名も自動的にピックアップさkubectl れるので、.NET Framework を使用する場合は明示的に参照する必要は kubectlありません。
KUBE_INGRESS_BASE_DOMAIN GitLab 11.8から、この変数を使ってクラスターごとにドメインを設定できるようになりました。 詳しくはクラスタドメインを参照してください。
注:GitLab 11.5以前では、KUBE_TOKEN 、クラスター統合のメインサービスアカウントのKubernetesトークンでした。
注意:GitLab 12.2以前にクラスターを作成した場合、デフォルトのKUBE_NAMESPACE は<project_name>-<project_id>に設定されます。

カスタム名前空間

GitLab 12.6 で導入されました。

Kubernetesインテグレーションは、デフォルトで<project_name>-<project_id>-<environment> （デプロイ変数を参照）という形式のプロジェクト環境固有の名前空間を使用します。

GitLabで管理されていないクラスターでは、.gitlab-ci.ymlのenvironment:kubernetes:namespaceを使って名前空間をカスタマイズすることができます。

Note:GitLabが管理するクラスターを使用する場合、ネームスペースはデプロイ前に自動的に作成され、カスタマイズすることはできません。

インテグレーション

カナリアのデプロイ

Kubernetesのカナリアデプロイを活用し、GitLabを離れることなく、デプロイボード内でカナリアデプロイを可視化できます。

カナリアのデプロイについてもっと読む

デプロイボード

GitLabのデプロイボードは、Kubernetes上で稼働する各CI環境の現在の健全性とステータスを統合的に表示し、デプロイ中のポッドのステータスを表示します。 開発者や他のチームメイトは、Kubernetesにアクセスする必要なく、既に使用しているワークフローでポッドごとにロールアウトの進捗とステータスを確認できます。

デプロイボードについてもっと読む

ポッドログの表示

GitLabは、接続されたKubernetesクラスターで実行中のポッドのログを簡単に表示することができます。 GitLabでログを直接表示することで、開発者はコンソールツールを管理したり、別のインターフェースにジャンプしたりする手間を省くことができます。

Kubernetesのログについてもっと読む

ウェブ端末

GitLab 8.15 で導入されました。

Kubernetesインテグレーションを有効にすると、環境にWebターミナルのサポートが追加されます。 これは、DockerとKubernetesにあるexec の機能に基づいているため、既存のコンテナ内で新しいシェルセッションを使用できます。 このインテグレーションを使用するには、上記のデプロイ変数を使用してKubernetesにデプロイし、デプロイメント、レプリカセット、ポッドにアノテーションが付けられていることを確認する必要があります：

  • app.gitlab.com/env: $CI_ENVIRONMENT_SLUG
  • app.gitlab.com/app: $CI_PROJECT_PATH_SLUG

$CI_ENVIRONMENT_SLUG と$CI_PROJECT_PATH_SLUG は CI 変数の値です。

ターミナルを使用するには、プロジェクトオーナーであるか、maintainer の権限が必要です。サポートは、環境の最初のポッドの最初のコンテナに限定されます。

トラブルシューティング

デプロイジョブが開始する前に、GitLabはデプロイジョブ専用に以下を作成します：

  • 名前空間。
  • サービスアカウント。

しかし、GitLabが作成できないこともあります。 そのようなインスタンスでは、ジョブはメッセージとともに失敗します： 

This job failed because the necessary resources were not successfully created.

ネームスペースとサービス・アカウントの作成時にこのエラーが発生する場合は、ログを確認してください。

失敗の理由は以下の通り：

  • GitLabに渡したトークンは、GitLabが必要とするcluster-adminの権限を持っていません。
  • KUBECONFIG またはKUBE_TOKEN 変数がありません。ジョブに渡すには、一致するenvironment:nameが必要です。ジョブにenvironment:name が設定されていない場合、Kubernetes クレデンシャルが渡されません。
注意:GitLab 12.0以前からアップグレードされたプロジェクトレベルのクラスターは、このエラーを引き起こす方法で設定されている可能性があります。 ネームスペースとサービスアカウントを自分で管理したい場合は、GitLab-managed clusterオプションを選択解除してください。

Kubernetesクラスターのモニタリング

Kubernetesのメトリクスを自動的に検出して監視します。 NGINXIngressの自動監視にも対応しています。

Kubernetesモニタリングについてもっと読む

クラスターの健全性の可視化

GitLab Ultimate10.6から導入されました。

Prometheusがデプロイされると、GitLabは自動的にクラスタの健全性を監視します。 クラスタの設定ページの上部には、CPUとメモリの使用率が、使用可能な合計量とともに表示されます。 クラスタのリソースを監視することは重要です。クラスタがメモリ不足になると、ポッドがシャットダウンされたり、起動に失敗したりする可能性があります。

Cluster Monitoring