チュートリアルLast Updated Oct 28, 202616 分 READ

CircleCI と Helm で Amazon EKS へのデプロイを自動化する

Vivek Maskara

ソフトウェア エンジニア

Kubernetes は、コンテナ化されたアプリケーションのデプロイの自動化と管理を行うためのコンテナオーケストレーションシステムです。Helm は Kubernetes のパッケージマネージャーで、Kubernetes アプリケーションの定義、インストール、アップグレードに役立ちます。Helm を使うと、Kubernetes のコンポーネント (Deployment、Service、HPA、ServiceAccount など) の再利用可能なテンプレートを定義し、アプリケーション間で公開・共有できます。

このチュートリアルでは、アプリケーション用の Helm チャートを作成し、AWS EKS クラスターにインストールする方法を学びます。Python の Flask アプリを作成して Docker 化し、そのアプリ用の Helm チャートを作成します。最後に、CircleCI を使って既存の AWS EKS クラスターへのデプロイを自動化します。

前提条件

このチュートリアルでは、Flask アプリを定義するために、システムに Python をセットアップする必要があります。また、アプリケーションをデプロイするための AWS アカウントと、デプロイを自動化するための CircleCI アカウントも必要です。

このチュートリアルに必要なものは、次のリストを参考にセットアップしてください。

開発中にローカルでセットアップをテストしたい場合は、さらにいくつかの準備が必要です。

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 リソースがアカウントにプロビジョニングされていることを確認してください。アカウント内の既存のリソースを使うことも、まだ作成していない場合は新しくプロビジョニングすることもできます。

クラスターを作成した 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 を選択してから一覧を更新してください。

Pipeline ステップの CircleCI Create a project ページ。パイプライン名 build-and-test、flask-helm-charts-circleci の GitHub リポジトリ、All pushes トリガーが選択されている

デフォルトの 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: クラスターを作成したリージョン。デフォルトのリージョンと同じ場合も、異なる場合もあります。

CircleCI のプロジェクト設定の Environment Variables ページ。このチュートリアルで使う 9 つの AWS 変数がマスクされた値で一覧表示されている

環境変数を設定したら、新しいコミットをプッシュするか、パイプラインがすでに実行されている場合は再実行します。今度はビルドが成功するはずです。

build_and_deploy ワークフローが 2 回成功した CircleCI のパイプライン。展開した実行では、aws-ecr/build_and_push_image ジョブと deploy_helm_chart ジョブの両方が成功している

クリーンアップ

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 で確認できます。