Kubernetes は、コンテナ化されたアプリケーションのデプロイの自動化と管理を行うためのコンテナオーケストレーションシステムです。Helm は Kubernetes のパッケージマネージャーで、Kubernetes アプリケーションの定義、インストール、アップグレードに役立ちます。Helm を使うと、Kubernetes のコンポーネント (Deployment、Service、HPA、ServiceAccount など) の再利用可能なテンプレートを定義し、アプリケーション間で公開・共有できます。
このチュートリアルでは、アプリケーション用の Helm チャートを作成し、AWS EKS クラスターにインストールする方法を学びます。Python の Flask アプリを作成して Docker 化し、そのアプリ用の Helm チャートを作成します。最後に、CircleCI を使って既存の AWS EKS クラスターへのデプロイを自動化します。
前提条件
このチュートリアルでは、Flask アプリを定義するために、システムに Python をセットアップする必要があります。また、アプリケーションをデプロイするための AWS アカウントと、デプロイを自動化するための CircleCI アカウントも必要です。
このチュートリアルに必要なものは、次のリストを参考にセットアップしてください。
- Python 3 をインストール
- Helm チャートのビルドとインストールに使う Helm CLI をインストール
- AWS アカウントと CircleCI アカウントを作成
開発中にローカルでセットアップをテストしたい場合は、さらにいくつかの準備が必要です。
- Docker イメージをローカルでビルドするために Docker をインストール
- クラスターをローカルでテストするために kubectl をインストール
- AWS CLI をインストールし、AWS の認証情報を設定
- Amazon EKS 上の Kubernetes クラスターを管理するために eksctl をインストール
Our tutorials are platform-agnostic, but use CircleCI as an example. If you don’t have a CircleCI account, sign up for a free one here.
Flask アプリの定義
このセクションでは、Python 3 でサンプルの Flask アプリを作成し、Docker でコンテナ化します。Flask は、Web アプリケーションを開発するためのオープンソースの Python フレームワークです。軽量なアプリケーションの API サービスレイヤーを構築する際によく使われています。
アプリの作成
まず、Flask プロジェクト用の新しいディレクトリを作成し、そこに移動します。次のように入力します。
mkdir flask-helm-charts-circleci
cd flask-helm-charts-circleci
次に、アプリのライブラリの依存関係を定義するために、flask-helm-charts-circleci ディレクトリに requirements.txt ファイルを作成します。この Python アプリは flask パッケージに依存しているので、requirements.txt ファイルに追加します。
Flask==3.1.3
flask-helm-charts-circleci ディレクトリに app.py ファイルを作成し、次のコードを追加します。
from flask import Flask
app = Flask(__name__)
@app.route('/')
def hello_world():
return 'Hello World!'
if __name__ == '__main__':
app.run(debug=False, host='0.0.0.0')
このコードスニペットは、静的なレスポンスを返す GET ルートを定義しています。ユースケースに応じて、hello_world メソッドに独自のロジックを追加できます。また、次のようなルートを追加することもできます。アプリの起動前に登録されるように、if __name__ == '__main__': の行より上に追加してください。
@app.route('/health')
def health_check():
return 'Health OK'
次のコマンドを実行すると、アプリをローカルで実行できます。このコマンドを実行すると、Flask アプリが localhost のポート 5000 で起動します。
python app.py
http://127.0.0.1:5000 にアクセスして、レスポンスを確認します。
アプリの Docker 化
Flask アプリを定義したら、アプリをコンテナ化するための Dockerfile を追加します。ここでは、Docker Hub の Python 3.14.9 slim ベースイメージを使います。flask-helm-charts-circleci ディレクトリに Dockerfile を作成し、次のコードスニペットを追加します。
FROM python:3.14.9-slim
ADD . /app
WORKDIR /app
RUN pip install -r requirements.txt
EXPOSE 5000
CMD ["python", "app.py"]
このコードスニペットは、次のステップで構成されています。
- Python 3.14.9 slim ベースイメージを使用します。
ADD .ステップで、プロジェクトのルートディレクトリにあるすべてのファイルを、コンテナの/appディレクトリにコピーします。WORKDIRで、コンテナの現在の作業ディレクトリを/appに設定します。以降のコマンドはすべてこのディレクトリで実行されます。RUNステップで、requirements.txtファイルに定義された Python の依存関係をインストールします。EXPOSEステップで、Docker コンテナのポート5000を公開します。- 最後に、
CMDでコンテナの起動コマンドを定義します。コンテナが実行されると、Flask アプリが起動します。
Docker コンテナのビルドと実行
Docker コンテナをローカルでビルドして実行し、期待どおりに動作するか確認します。CircleCI を使ってセットアップする予定であれば、この手順はスキップしてかまいません。
Docker イメージをビルドするには、flask-helm-charts-circleci ディレクトリで次のコマンドを実行します。
docker build -t flask-hello-world .
注: 上記のコマンドを実行する前に、システムに Docker がインストールされていることを確認してください。インストール手順については、前提条件セクションのリンクをご覧ください。
最後に、次のコマンドを実行します。
docker run -it --rm -p 5001:5000 flask-hello-world:latest
このコマンドは、Docker コンテナのポート 5000 をローカルのポート 5001 に転送します。http://127.0.0.1:5001 にアクセスして、アプリが期待どおりに動作していることを確認してください。
AWS リソースの作成
テストとデプロイに進む前に、必要な AWS リソースがアカウントにプロビジョニングされていることを確認してください。アカウント内の既存のリソースを使うことも、まだ作成していない場合は新しくプロビジョニングすることもできます。
- Flask の Docker イメージをホストするための AWS ECR リポジトリを作成
- Helm チャートをホストするための AWS ECR リポジトリを作成
- Kubernetes のワークロードを実行するための AWS EKS クラスターを作成
クラスターを作成した IAM アイデンティティには、クラスター管理者のアクセス権が自動的に付与されます。CircleCI で別の IAM ユーザーまたはロールを設定する場合は、EKS アクセスエントリを使って、そのユーザーまたはロールにクラスターへのアクセス権を付与してください。
Helm チャートの作成
チャートは Helm のパッケージ形式です。チャートには、関連する一連の Kubernetes リソースを記述したファイルがまとめて含まれています。このセクションでは、アプリ用の Helm チャートを定義します。
アプリ用のチャートを作成するには、flask-helm-charts-circleci ディレクトリで次のコマンドを実行します。
helm create charts
注: 上記のコマンドを実行する前に、Helm CLI をインストールしてください。インストール手順については、前提条件セクションのリンクをご覧ください。
このコマンドを実行すると、次の構成の charts ディレクトリが作成されます。
charts/
Chart.yaml
values.yaml
charts/
templates/
charts/templates/ ディレクトリにはいくつかのファイルが含まれていますが、必要なのは _helpers.tpl、deployment.yaml、service.yaml だけです。templates ディレクトリからそれ以外のファイルを削除します。
次に、Deployment のテンプレートを更新して、このチュートリアルでは不要な変数を削除します。また、Flask アプリケーションはポート 5000 で実行されているため、containerPort を 5000 に更新する必要があります。charts/templates/deployment.yaml の内容を次のコードスニペットに置き換えます。
apiVersion: apps/v1
kind: Deployment
metadata:
name: {{ include "charts.fullname" . }}
labels:
{{- include "charts.labels" . | nindent 4 }}
spec:
{{- if not .Values.autoscaling.enabled }}
replicas: {{ .Values.replicaCount }}
{{- end }}
selector:
matchLabels:
{{- include "charts.selectorLabels" . | nindent 6 }}
template:
metadata:
{{- with .Values.podAnnotations }}
annotations:
{{- toYaml . | nindent 8 }}
{{- end }}
labels:
{{- include "charts.selectorLabels" . | nindent 8 }}
spec:
{{- with .Values.imagePullSecrets }}
imagePullSecrets:
{{- toYaml . | nindent 8 }}
{{- end }}
containers:
- name: {{ .Chart.Name }}
image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
imagePullPolicy: {{ .Values.image.pullPolicy }}
ports:
- name: http
containerPort: 5000
protocol: TCP
livenessProbe:
httpGet:
path: /
port: http
readinessProbe:
httpGet:
path: /
port: http
次に、values.yaml ファイルを、アプリケーションに対応する値で更新します。charts/values.yaml の内容を次のコードスニペットに置き換えます。
replicaCount: 1
image:
repository: <AWS_ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com/<AWS_ECR_REPO_NAME>
pullPolicy: IfNotPresent
tag: "latest"
labels:
env: "staging"
service:
port: 5000
type: LoadBalancer
autoscaling:
enabled: false
ingress:
enabled: false
<AWS_ACCOUNT_ID> は AWS アカウント ID に、<AWS_REGION> は AWS のデプロイ先リージョンに、<AWS_ECR_REPO_NAME> は Flask の Docker イメージ用の AWS ECR リポジトリ名に置き換えてください。
次に、charts/Chart.yaml の name を更新します。
name: flask-helm-chart
チャート名は、Helm 用の AWS ECR リポジトリ名と一致させる必要があります。
ローカルでのテスト
CircleCI でデプロイを自動化する前に、ローカルでセットアップをテストしておくとよいでしょう。このセクションでは、イメージと Helm チャートを手動で AWS ECR にプッシュし、Helm チャートを AWS EKS クラスターにデプロイする方法を説明します。CircleCI ですぐにデプロイを自動化したい場合は、このセクションをスキップしてかまいません。
Docker イメージを ECR にプッシュする
Docker イメージをプッシュする前に、Docker を AWS ECR で認証する必要があります。認証のために次のコマンドを実行します。
aws ecr get-login-password --region <AWS_REGION> | docker login --username AWS --password-stdin <AWS_ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com
上記のコマンドを実行する前に、AWS CLI をインストールし、AWS の認証情報を設定しておく必要があります。手順については、前提条件セクションのリンクをご覧ください。
次に、前のセクションでビルドした Docker イメージに、次のコマンドでタグを付けます。
docker tag flask-hello-world:latest <AWS_ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com/flask-hello-world
AWS アカウントに flask-hello-world という名前の ECR リポジトリがあることを確認してください。
次のコマンドを実行して、Docker イメージを AWS ECR リポジトリにプッシュします。
docker push <AWS_ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com/flask-hello-world:latest
Helm チャートを ECR にプッシュする
Helm チャートをプッシュする前に、helm を AWS ECR で認証する必要があります。認証のために次のコマンドを実行します。
aws ecr get-login-password --region <AWS_REGION> | helm registry login --username AWS --password-stdin <AWS_ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com
次に、プロジェクトのルートディレクトリで次のコマンドを実行して、Helm チャートをパッケージ化します。
helm package charts
Helm チャートを圧縮した flask-helm-chart-0.1.0.tgz ファイルが生成されます。
tgz のファイル名は、charts/Chart.yaml で定義したチャート名によって異なる場合があります。
次のコマンドを実行すると、Helm チャートを AWS ECR リポジトリにプッシュできます。
helm push flask-helm-chart-0.1.0.tgz oci://<AWS_ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com/
Helm チャートを AWS EKS にデプロイする
Helm チャートを AWS ECR リポジトリにプッシュしたので、AWS EKS クラスターにデプロイできます。まず、AWS CLI を使ってローカルの kube の設定を更新します。
aws eks update-kubeconfig --region <AWS_REGION> --name <AWS_EKS_CLUSTER_NAME>
<AWS_EKS_CLUSTER_NAME> は AWS EKS クラスターの名前に、<AWS_REGION> は選択した AWS リージョンの名前に置き換えてください。
このコマンドは、kube の設定を $HOME/.kube/config に書き込みます。
最後に、helm install コマンドを実行して、チャートを EKS クラスターにインストールします。
helm install flask-helm oci://<AWS_ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.com/flask-helm-chart --version 0.1.0
このコマンドで、ワークロードが EKS クラスターにインストールされます。クラスター上の pods を確認して、インストールされたことを確かめられます。
kubectl get pods
CircleCI を使ったデプロイの自動化
Kubernetes クラスターをローカルでテストできたので、コードをプッシュするたびに変更がデプロイされるようにワークフローを自動化しましょう。デプロイを自動化するには、次の作業が必要です。
- Helm のデプロイコマンドを選ぶ
- 設定スクリプトを追加する
- CircleCI でプロジェクトをセットアップする
Helm のデプロイコマンドを選ぶ
チャートがすでにクラスターにインストールされている場合、helm install は失敗するため、代わりに helm upgrade が必要になります。helm upgrade --install コマンドは、この両方のケースに対応します。flask-helm リリースがまだ存在しなければインストールし、存在すればアップグレードします。次のセクションの CircleCI の設定では、このコマンドを使ってデプロイします。
helm upgrade --install flask-helm oci://$AWS_ECR_ACCOUNT_URL/$AWS_ECR_HELM_REPO_NAME --version 1.0.0
設定スクリプトを追加する
まず、プロジェクトのルートに、CI パイプラインの設定を記述した .circleci/config.yml スクリプトを追加します。次のコードスニペットを追加します。
version: 2.1
orbs:
aws-cli: circleci/aws-cli@5.4.2
aws-ecr: circleci/aws-ecr@10.0.0
jobs:
deploy_helm_chart:
docker:
- image: cimg/python:3.14.9
steps:
- checkout
- aws-cli/setup
- run:
name: Install Helm
command: |
curl -fsSL https://get.helm.sh/helm-v4.3.1-linux-amd64.tar.gz | tar xz
sudo mv linux-amd64/helm /usr/local/bin/helm && rm -rf linux-amd64
helm version
- run:
name: Configure access to the EKS cluster
command: aws eks update-kubeconfig --region $AWS_CLUSTER_REGION --name $AWS_EKS_CLUSTER_NAME
- run:
name: Push the Helm chart to ECR
command: |
aws ecr get-login-password --region $AWS_DEFAULT_REGION | helm registry login --username AWS --password-stdin $AWS_ECR_ACCOUNT_URL
helm package charts --version 1.0.0 --destination dist
helm push dist/*.tgz oci://$AWS_ECR_ACCOUNT_URL
- run:
name: Install or upgrade the Helm release
command: |
helm upgrade --install flask-helm oci://$AWS_ECR_ACCOUNT_URL/$AWS_ECR_HELM_REPO_NAME --version 1.0.0 \
--set image.repository=$AWS_ECR_ACCOUNT_URL/$AWS_ECR_REPO_NAME --set-string image.tag=$CIRCLE_SHA1 \
--wait --timeout 5m
workflows:
build_and_deploy:
jobs:
- aws-ecr/build_and_push_image:
auth:
- aws-cli/setup
repo: ${AWS_ECR_REPO_NAME}
tag: latest,${CIRCLE_SHA1}
- deploy_helm_chart:
requires:
- aws-ecr/build_and_push_image
CircleCI の設定を確認してみましょう。このワークフローは 2 つのジョブを実行します。
aws-ecr/build_and_push_imageジョブは、aws-ecr Orb を使って Flask の Docker イメージをビルドし、AWS ECR リポジトリにプッシュします。このジョブのauthステップでは、aws-cli Orb を使い、プロジェクトの環境変数に設定した AWS の認証情報でサインインします。イメージにはlatestとコミットの SHA のタグが付けられます。deploy_helm_chartジョブは、Helm チャートを Helm 用の AWS ECR リポジトリにプッシュし、AWS EKS クラスターにインストールします。このジョブは次のステップで構成されています。- aws-cli Orb で AWS CLI をインストールしてから、Helm CLI をインストールします。
aws eks update-kubeconfigを使って、kube の設定を$HOME/.kube/configに書き込みます。- Helm を AWS ECR で認証してから、チャートをパッケージ化してプッシュします。
helm upgrade --installでチャートをデプロイします。image.repositoryを環境変数から、image.tagをコミットの SHA から設定するため、パイプラインを実行するたびに、ビルドしたばかりのイメージがロールアウトされます。
設定ファイルの準備ができたら、GitHub にプロジェクト用のリポジトリを作成し、すべてのコードをプッシュします。手順については、プロジェクトを GitHub にプッシュする方法 (英語) をご覧ください。
CircleCI でプロジェクトをセットアップする
次に、CircleCI アカウントにログインします。CircleCI の Web アプリで組織を選択し、Create project を選択します。プロジェクトに名前を付けて Next を選択します。提案されたパイプライン名をそのまま使うか、独自の名前を入力して、GitHub リポジトリを選択します。CircleCI がまだ GitHub に接続されていない場合は、+ (Add a provider) ボタンを選択し、リポジトリに CircleCI GitHub App をインストールします。リポジトリが一覧に表示されない場合は、Update access on GitHub を選択してから一覧を更新してください。
デフォルトの All pushes トリガーはそのままにして、Next を選択します。CircleCI は、リポジトリ内の .circleci/config.yml ファイルを検出します。もう一度 Next を選択し、セットアップ内容を確認して Go to project を選択します。
パイプラインは、次にリポジトリにプッシュしたときに実行されます。環境変数を定義する前に実行された場合、パイプラインは失敗します。
環境変数のセットアップ
プロジェクトのパイプラインページで Project メニューを開いて Project settings を選択し、サイドナビゲーションで Environment Variables を選択します。Add を選択して、新しいキーと値を追加します。
次の環境変数を追加します。
AWS_ACCESS_KEY_ID: AWS の認証情報の作成時に取得したアクセスキーAWS_SECRET_ACCESS_KEY: AWS の認証情報の作成時に取得したシークレットAWS_DEFAULT_REGION: アプリケーションをデプロイするリージョンAWS_ACCOUNT_ID: 12 桁の AWS アカウント ID。aws-ecr Orb はこの値を使ってレジストリの URL を組み立てます。AWS_ECR_ACCOUNT_URL: AWS アカウントの URL。<AWS_ACCOUNT_ID>.dkr.ecr.<AWS_REGION>.amazonaws.comの AWS アカウント ID とリージョンを実際の値に置き換えたものをアカウントの URL として設定します。AWS_ECR_HELM_REPO_NAME: Helm チャート用の AWS ECR リポジトリ名AWS_ECR_REPO_NAME: Flask アプリケーションの Docker イメージ用の AWS ECR リポジトリ名AWS_EKS_CLUSTER_NAME: AWS EKS クラスターの名前AWS_CLUSTER_REGION: クラスターを作成したリージョン。デフォルトのリージョンと同じ場合も、異なる場合もあります。
環境変数を設定したら、新しいコミットをプッシュするか、パイプラインがすでに実行されている場合は再実行します。今度はビルドが成功するはずです。
クリーンアップ
EKS クラスター、そのノード、および LoadBalancer サービス用に作成されたロードバランサーは、削除するまで稼働し続け、料金が発生します。作業が終わったら、リリースをアンインストールします。これにより、ロードバランサーも削除されます。
helm uninstall flask-helm
次に、EKS クラスターを削除します。2 つの ECR リポジトリが不要になった場合は、それらも削除します。
aws ecr delete-repository --repository-name <AWS_ECR_REPO_NAME> --region <AWS_REGION> --force
aws ecr delete-repository --repository-name <AWS_ECR_HELM_REPO_NAME> --region <AWS_REGION> --force
まとめ
このチュートリアルでは、CircleCI を使って Helm チャートを自動的にビルドし、AWS EKS クラスターにデプロイする方法を学びました。Helm チャートを使うと、再利用可能なテンプレートによってクラスターの複雑さに対処しやすくなり、クラスターの更新プロセスもシンプルになります。また、Helm チャートのバージョン管理や共有、パブリックまたはプライベートなサーバーでのホストも簡単に行えます。CircleCI を使えば、継続的デリバリーのためのビルドとデプロイのパイプラインを自動化できます。このパイプラインで、Docker イメージと Helm チャートを AWS ECR リポジトリにプッシュし、新しいワークロードで EKS クラスターを更新できます。
このチュートリアルで使用した完全なソースコードは GitHub で確認できます。