Kubernetes ベースのアプリケーション を運用する開発チームにとって、デプロイプロセスの可視化と管理を維持することは簡単なことではありません。一元化されたインターフェースがないと、複数の Kubernetes クラスターにまたがるリリースの追跡や監視、管理が困難だからです。その結果、デプロイミスに気づくのが遅れたり、一貫したデプロイワークフローを維持できなくなったりします。
特に、標準の Kubernetes デプロイと Argo Rollouts などの高度な戦略を併用している場合、リリース全体を統合的にオーケストレーションするソリューションが不可欠です。
それを可能にしてくれるのが CircleCI Deploys です。CircleCI 上で直接 Kubernetes のデプロイ状況を可視化し、ダッシュボードからのコマンド実行を可能にします。本記事では、この機能のセットアップからリリース管理の方法までを徹底解説します。
前提条件
作業を開始する前に、以下の環境が整っていることを確認してください。
- CircleCI アカウント（無料プランでOK）
- Amazon Elastic Kubernetes Service (EKS) クラスター
- CircleCI プロジェクト（ソースコードと連携済みであること）
- Helm
（ローカル環境にインストール済み）
本ガイドの対象：誰がどの作業を担当するか
組織の体制やフェーズによって、Kubernetes 周りの役割分担はさまざまです。本記事で紹介する手順は、大きく分けて以下の2つの役割（チーム）を対象としています。
-
プラットフォームエンジニアリングチーム：EKS クラスターの構築、Release Agent のセットアップと構成。開発者がスムーズにデプロイできるための「基盤」を整えます。
-
アプリケーション開発チーム：Kubernetes マニフェストへの修正を最小限に抑えつつ、アプリのセットアップや日々のリリース管理を実施。開発・テスト・本番といったライフサイクルごとに用意された名前空間（Namespace）へのアクセス権をリクエストし、セルフサービス形式でデプロイを進めるチームを想定しています。
デプロイの設定
CircleCI でリリース管理を始めるには、まず CircleCI が対象のプラットフォームと連携するための環境設定 が必要です。
本記事では、Kubernetes ベースのセットアップを例に、CircleCI Deploys の主要な機能を紹介します。
CircleCI がデプロイのバージョンを追跡・管理するためには、EKS クラスターに Kubernetes Release Agent をインストールする必要があります。 Kubernetes や Helm の最新情報やサポートされているバージョンについては、CircleCI Kubernetes Release Agent のドキュメントを参照してください。
環境インテグレーションの作成
CircleCI の Deploys ページから、新しい環境を作成します。
- Name：dev
- Description：Development environment
- Type：Kubernetes Cluster
（デフォルトで選択されています）
リリース エージェントのセットアップ
Kubernetes Release Agent は、EKS クラスター内のデプロイやロールアウト イベントを監視し、CircleCI プラットフォームから一般的な Kubernetes コマンドを実行できるようにします。これには、デプロイ失敗時の正常な旧バージョンへのロールバックや、デプロイのスケーリングなどが含まれます。
クラスターの構築が完了したら、Kubernetes コントロール プレーンに対して CLI アクセスができる環境からリリース エージェントをインストールできます。たとえば、circleci という名前の EKS クラスターの場合、以下のコマンドを実行して最新の kubeconfig を取得します。
aws eks update-kubeconfig --region us-east-1 --name circleci
ローカル Helm リポジトリを更新して cci-k8s-release-agent を追加し、キャッシュを更新して最新バージョンであることを確認します。
helm repo add release-agent https://circleci-public.github.io/cci-k8s-release-agent
helm repo update
リリース エージェントを EKS クラスターにインストールするには、いくつかのパラメーターが必要になります。
- 環境インテグレーション トークン (Environment integration token)
- エージェントをインストールする名前空間（デフォルト：
circleci-release-agent-system） - 管理・監視対象の名前空間（デフォルト：
default）
Terraform の Helm プロバイダーを使用して、EKS クラスターの構築と併せて CircleCI の設定ファイル（config.yml）内からコマンドを実行することも可能ですが、本記事では Helm CLI コマンドを使用した手順を解説します。
helm upgrade --install circleci-release-agent-system release-agent/circleci-release-agent \
--set tokenSecret.token=<token> \
--create-namespace \
--namespace circleci-release-agent-system \
--set managedNamespaces="{default}" # you can specify a comma separated list of namespaces
Release "circleci-release-agent-system" does not exist. Installing it now.
NAME: circleci-release-agent-system
LAST DEPLOYED: Tue Jan 23 23:24:17 2025
NAMESPACE: circleci-release-agent-system
STATUS: deployed
REVISION: 1
TEST SUITE: None
エージェントのインストールが完了し、クラスターとリリース エージェントの間の通信が確立されると、セットアップ画面のステータスが「ONLINE」になります。
コンポーネントの設定
CircleCI における「コンポーネント」とは、単一のユニットとしてデプロイおよびリリースされるコードと設定の集合体です。Kubernetes の用語に置き換えると、共通の circleci.com/component-name ラベルを共有する Deployment や Rollout オブジェクト、およびそれに関連する Pod や ReplicaSet などのオブジェクトを指します。
CircleCI でリリースとデプロイを追跡できるようにするために、既存の Kubernetes デプロイ マニフェストへ追加する必要がある変更は、CircleCI Deploys 用のアノテーションとラベルの追加のみです。
annotations:
circleci.com/project-id:
labels:
circleci.com/component-name: example-deployment
circleci.com/version: 1.0.0
リリースの機能を詳しく確認するために、Kubernetes チュートリアルのデプロイとサービスの設定サンプルを以下に示します。これは、component-name とバージョンを指定したレンダリング済みのテンプレートです。
#nginx.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: nginx-deployment
annotations:
circleci.com/project-id: e6e31da9-5007-409b-88dd-6263c3dc5e8d
labels:
app: nginx
circleci.com/component-name: nginx
circleci.com/version: 1.0.1
spec:
replicas: 3
selector:
matchLabels:
app: nginx
template:
metadata:
labels:
app: nginx
circleci.com/component-name: nginx
circleci.com/version: 1.0.1
spec:
containers:
- name: nginx
image: nginx:1.14.2
ports:
- containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
name: nginx-service
spec:
selector:
app: nginx
ports:
- name: https
protocol: TCP
port: 80
targetPort: 9376
Kubernetes マニフェストは、ローカル マシンから適用することも、CircleCI パイプライン経由で適用することも可能です。パイプラインを利用する場合、環境変数の置換を使用してプロジェクト ID を動的に追加できます。この例では、コマンドラインからデプロイを実行します。
kubectl apply -f nginx.yaml
また、以下のような高度な設定も可能です。
- コンポーネントのリリーストリガーを CircleCI のデプロイ ジョブに設定する
- カスタム アノテーションを使用して、CircleCI 上で利用可能なアクションをカスタマイズする
セットアップが完了すると、コンポーネント ラベルに基づいて、あらゆるデプロイやリリースを CircleCI 上で追跡できるようになります。
リリース管理
アプリケーションのデプロイを数回 EKS クラスターに対して実行すると、CircleCI 上で各バージョンのステータスやバージョン番号、および（設定されている場合は）リリーストリガーの状況を一覧で確認できるようになります。
リリースバージョンをロールバックする
CircleCI では、「Restore this version」をクリックするだけで、以前の正常なバージョンを簡単にロールバックできます。これは、コンポーネントを操作するために CircleCI 上で実行できるユーザー主導アクションの 1 つです。Helm を使用してデプロイを行っている場合、この操作は Helm ロールバックを実行するのと同等です。
バージョンのロールバックは、リリース エージェントを介して CircleCI から実行され、その実行結果は CircleCI のプラットフォームへ即座に報告されます。
実際の運用シナリオでは、CircleCI 上でのロールバック操作に合わせて、対象リリースのパイプラインをトリガーした Git リポジトリ側のコミット内容も修正（リバートなど）し、コードとデプロイ状態の整合性を保つことを推奨します。
コンポーネントのスケーリング
CircleCI 上の「稼働中のバージョン（Active versions）」から、コンポーネントを直接スケーリングすることも可能です。
CircleCI からスケーリングのコマンドが発行されると、そのコマンドの内容に加え、実行したユーザーや実行時刻などの情報が記録されます。これらのデータは監査ログ（Audit trail）として保存されるため、後から操作履歴を正確に把握することができます。
まとめ
本記事では、標準的なデプロイ パターンにおいて CircleCI Deploys を活用し、EKS ベースのデプロイを管理する手順を詳しく解説しました。
CircleCI Deploys は Argo Rollouts もサポートしており、導入することで CircleCI プラットフォーム上での制御機能をさらに拡張できます。これにより、ロールアウトの再試行、進行（Promote）、デプロイのキャンセルといった高度な操作を、CircleCI の画面上から直接、柔軟に行うことが可能になります。
Kubernetes デプロイをより効率化する準備はできましたか？まずはクイックスタートガイドを参考に、ご自身の EKS クラスターで CircleCI Deploys を体験してみてください。
Argo Rollouts のサポートや、機械学習（ML）モデルのデプロイを支える Amazon SageMaker との連携など、さらに強化されたリリース管理機能をぜひご活用ください。より詳しい情報については、以下の包括的なドキュメントを参照してください。
