1.はじめに
1.1.背景
社内で Amazon Q Developer CLI の勉強会を予定していますが、それぞれ参加者が異なる環境のため足並みが揃わないことを想定し、まずはWindowsユーザ向けの環境構築ハンズオンを作成しました。
1.2.WSL2とは
- WSL2（Windows Subsystem for Linux 2）は、Windows上でLinuxを動かすためのMicrosoft公式の仕組みです。
これにより Windows内でLinuxコマンドやツールが使えるようになり、DockerやKubernetesなどのコンテナ技術が使えるようになります。
1.3.Finchとは
- Finch（フィンチ）は、AWSが開発したオープンソースのコンテナ開発ツールです。
Dockerのようにコンテナイメージのビルド・実行が可能で、AWSサービスとの連携がスムーズという特徴があります。
2.ハンズオン
2.1.前提条件
- Windows 11 (x86-64) / Windows 10 バージョン 1903 以降、ビルド 18362.1049 (x86-64)
- BIOSで仮想化が有効になっていること
- 管理者権限でPowerShellを実行できること
2.1.1.Widowsのバージョン確認方法
- 「Windows + R」を押下し「winver.exe」を実行
- 「ビルド」番号が 18362 より大きい場合「WSL 2」と「Finch」がサポートされます。
■ コマンド実行後表示される画面
2.1.2.BIOSで仮想化が有効になっていることの確認
- タスクマネージャ(Ctrl + Shift + Esc) を開き、パフォーマンスタブ「CPU」を開く
- 右下部分「仮想化：有効」と表示されていることを確認
■ 赤枠部分を確認
2.2.WSL インストール
- PowerShellを
管理者権限で実行 - WSLを使ってWindowsにLinuxをインストールする方法に従い、インストールを実施する。
# WSLインストール
wsl --install
- 以下の実行結果が表示されたあと、
PowerShellを再起動させる- PowerShellのウィンドウを一度閉じて、再度管理者権限で起動してください
# 実行結果
システムを再起動する必要があります。
# 再起動(PowerShellのセッションが終了)
exit
2.3.ディストリビューションのインストール
2.3.1.インストール可能な一覧表示
# 利用可能なLinuxディストリビューションの確認
wsl.exe --list --online
# 実行結果
NAME FRIENDLY NAME
AlmaLinux-8 AlmaLinux OS 8
<中略>
OracleLinux_9_1 Oracle Linux 9.1
2.3.2.Ubuntu インストールの場合
-
wsl.exe --install <Distro>を使用してインストールすることが可能。
# 今回は Ubuntu をインストールしてみる
wsl.exe --install Ubuntu
# 実行結果
ディストリビューションが正常にインストールされました。'wsl.exe -d Ubuntu' を使用して起動できます
2.3.3.インストール確認
# インストール状況を確認
wsl.exe -l -v
# 実行結果
NAME STATE VERSION
* Ubuntu Stopped 2
# ステータス確認
wsl.exe --status
# 実行結果
既定のディストリビューション: Ubuntu
既定のバージョン: 2
# 再起動
exit
2.3.4.Ubuntu インストール時に発生したエラー
- 以下エラーが検証の際に発生しました。
# エラー内容
既定のバージョン: 2
WSL1 は、現在のマシン構成ではサポートされていません。
WSL1 を使用するには、"Linux 用 Windows サブシステム" オプション コンポーネントを有効にしてください。
WSL2 は、現在のマシン構成ではサポートされていません。
"仮想マシン プラットフォーム" オプション コンポーネントを有効にし、さらに、BIOS で仮想化を有効にしてください。
"仮想マシン プラットフォーム" を有効にするには、次のコマンドを実行します: wsl.exe --install --no-distribution
- 想定原因：仮想化は有効だったけど、Windowsがそれを正しく認識できてなかったため発生と想定。
- 対応方法：エラー文にある
wsl.exe --install --no-distributionで、仮想マシンプラットフォームを再有効化する。
# Linuxディストリビューションはインストールせず、仮想マシンプラットフォームだけインストール/修復
wsl.exe --install --no-distribution
# 実行結果
要求された操作は正常に終了しました。変更を有効にするには、システムを再起動する必要があります
# 再起動
exit
- ここまで実行終わったら、再度
2.3.2を実施
2.4.Finchのインストール
2.4.1.ダウンロード
-
FinchのGitHubリポジトリから最新の
Finch.msiをダウンロード
■ ブログ記載時(2025/5/25)の GitHubの画面、赤枠部分を押下してダウンロード
2.4.2.インストーラ画面
2.4.3.ライセンス同意
- Finch ライセンスを読んで同意し、「次へ」をクリック
2.4.4.インストール先を選択
- デフォルトの場所と異なる場合はインストール場所を選択し、「次へ」をクリック
2.4.5.インストール押下
- 押下するとインストールが開始される
2.4.6.インストール完了画面
- Finch のインストールが完了したら、「完了」を押してインストール ウィンドウを閉じる
2.4.7.インストール確認
- PowerShellを起動して、以下コマンドを実行
- 初期セットアップには通常約1分かかり、ユーザーのパスワードが再度要求される場合がある。
# Finchのバージョン確認
finch version
# 仮想マシンの初期化
finch vm init
# Finch デモ コンテナ イメージを実行
finch run public.ecr.aws/finch/hello-finch:latest
# 実行結果
@@@@@@@@@@@@@@@@@@@
@@@@@@@@@@@@ @@@@@@@@@@@
@@@@@@@ @@@@@@@
@@@@@@ @@@@@@
@@@@@@ @@@@@
@@@@@ @@@# @@@@@@@@@
@@@@@ @@ @@@ @@@@@@@@@@
@@@@% @ @@ @@@@@@@@@@@
@@@@ @@@@@@@@
@@@@ @@@@@@@@@@@&
@@@@@ &@@@@@@@@@@@
@@@@@ @@@@@@@@
@@@@@ @@@@@(
@@@@@@ @@@@@@
@@@@@@@ @@@@@@@
@@@@@@@@@@@@@@@@@@@@@@@@@@
@@@@@@@@@@@@@@@@@@
Hello from Finch!
Visit us @ github.com/runfinch
2.5.コンテナイメージの作成
2.5.1.作業ディレクトリ作成
- WSLの
Ubuntuを起動して、作業ディレクトリに移動(任意のディレクトリ)して Dockerfileを作成。
# Ubuntを起動
wsl.exe -d Ubuntu
# 作業ディレクトリ(任意のディレクトリ)に移動して作業ディレクトリ作成
cd (任意のディレクトリ名)
mkdir aws-q-project
cd aws-q-project
2.5.2.Dockerfile作成
# Dockerfile作成
cat > Dockerfile << EOF
FROM debian:bookworm-slim
# Update package lists and install curl in one layer
RUN apt-get update && \
apt-get install -y curl unzip && \
curl https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip -o awscliv2.zip && \
unzip -q awscliv2.zip && \
./aws/install && \
curl --proto '=https' --tlsv1.2 -sSf https://desktop-release.q.us-east-1.amazonaws.com/latest/amazon-q.deb -o amazon-q.deb && \
apt-get install -y ./amazon-q.deb && \
apt-get clean && \
rm -rf /var/lib/apt/lists/* amazon-q.deb ./aws awscliv2.zip
# Set the working directory to /app
WORKDIR /app
# Run the application
ENTRYPOINT ["q"]
CMD ["chat"]
EOF
2.5.3.FinchのVMを起動
-
2.5.2作成後Ubuntu環境からexitして、Finchを起動(すでに起動済みの場合は不要)- 以下コマンド
finch vm statusで停止しているか確認可能
- 以下コマンド
# Ubuntuからexit
exit
# FinchのVMを起動
finch vm start
2.5.3.Finchでビルド実行
-
qprojectという名前のコンテナイメージを作成
# Dockerfileを配置したフォルダへ移動
cd (任意のディレクトリ名)\aws-q-project
# コンテナイメージをビルド
finch build -t qproject .
2.6.コンテナを起動してログイン
2.6.1.コマンド意味
| No. | Widows(左側) | コンテナ(右側) | 詳細 |
|---|---|---|---|
| 1 | ${PWD}/app: | /app | 作業ファイルをWindows側に保存 |
| 2 | ${PWD}/.local: | /root/.local | ログイン情報を永続化 |
| 3 | ${PWD}/.aws: | /root/.aws | AWS認証情報 |
2.6.2.ハンズオン
# コンテナを実行してログイン
finch run -it `
-v ${PWD}/app:/app `
-v ${PWD}/.local:/root/.local `
-v ${PWD}/.aws:/root/.aws `
qproject login
2.6.2.ウィザード回答
- Amazon Q Developerを無料で利用するため
Use for Free with Builder IDを選択
-Open this URLのURLでログイン
# ライセンス選択
> Use for Free with Builder ID
Use with Pro license
# 実行結果
Open this URL: https://view.awsapps.com/start/#/device?user_code=XXXX-XXXX
2.6.3.ブラウザで認証(= Q Developer CLIが利用できる状態)
-
2.7.2のURLからログインを実施しアクセスを許可を押下 - この時点では
AWS認証情報が設定されていないため、Q Developer CLIを起動してもリソースの取得などは出来ません。
2.6.4.AWS認証情報設定
- Q Developer CLIでリソースの確認が出来るように
AWS認証情報の設定
# AWSの認証情報をセット
finch run -it `
-v ${PWD}/app:/app `
-v ${PWD}/.local:/root/.local `
-v ${PWD}/.aws:/root/.aws `
--entrypoint bash `
qproject
# コンテナ内でAWS コンフィグ設定
root@46a63ba33e08:/app# aws configure
AWS Access Key ID [None]: XXXXXXXXX
AWS Secret Access Key [None]: YYYYYYYYYY
Default region name [None]: us-east-1
Default output format [None]: json
# 上記実施後 Bashシェル終了
exit
2.7.Q Developer CLIでエージェントの起動
finch run -it `
-v ${PWD}/app:/app `
-v ${PWD}/.local:/root/.local `
-v ${PWD}/.aws:/root/.aws `
qproject
2.8.実行画面
- 無事に実行することが確認出来ました。
2.9.実行環境のクリーンアップ
- 以下コマンドを実行することで、コンテナは正常に終了・削除される
# Q Developer CLIの停止
/quit
3.おわりに
3.1.得られた知見
- WSL2の仮想マシンプラットフォームの設定方法
- ボリュームマウントにより作業ファイルとログイン情報の永続化が可能
3.2.今後の課題
- .Q Developer CLIの利用方法