第1回：環境とツール準備（AOSS × Bedrock RAGの下地づくり

この記事のゴール
Amazon OpenSearch Serverless（AOSS）とAmazon Bedrockを使ったRAGの構築に向けて、コマンドが素直に通る環境を作ります。
単なる「正しい手順」だけでなく、実際に踏み抜いた**失敗と対処（FAQ）**も添えています。

1. 必要ツール
1. 1.1 インストール/更新
2. 環境変数
1. 2.1 .env 運用（おすすめ）
3. スモークテスト（壊れていないかを最初に見る）
4. 便利なスタータースクリプト（コピペOK）
1. 4.1 01_env_setup.sh
5. 失敗と対処（FAQ：この回）
6. 次に進む前のチェックリスト

1. 必要ツール

Tool	Purpose
AWS CLI v2	AOSSのコレクション/ポリシー操作
jq	CLIのJSON整形/抽出
Bash	スクリプト実行
Python（opensearch-py, boto3, requests, requests-aws4auth）	AOSS接続・疎通テスト

1.1 インストール/更新

AWS CLI v2

macOS（Homebrew） brew install awscli brew upgrade awscli
Ubuntu / WSL curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o awscliv2.zip unzip awscliv2.zip sudo ./aws/install --update
動作確認 aws --version aws opensearchserverless help | head -n 5

# macOS brew install jq # Ubuntu / WSL sudo apt-get update && sudo apt-get install -y jq jq --version

Pythonパッケージ
（venv推奨ですが、必須ではありません）

# ① venv（任意） python3 -m venv venv source venv/bin/activate # ② 必須ライブラリ pip install --upgrade pip pip install opensearch-py boto3 requests requests-aws4auth

2. 環境変数

学習・運用で繰り返し使う値を一括で管理します。
AWS_PROFILE を省略したい場合は未設定でOK。

export REGION=ap-northeast-1 export AWS_PROFILE=default # 未設定でも可 export PROJECT=itcometrueacademy export ENV=dev export COLLECTION_NAME="${PROJECT}-${ENV}" # itcometrueacademy-dev export INDEX_NAME="${PROJECT}-${ENV}-docs" # itcometrueacademy-dev-docs # CLIでプロファイルを「定義されている時だけ」付けるためのヘルパ AWSP="${AWS_PROFILE:+--profile $AWS_PROFILE}" # 同系のコードが AWS_REGION を参照する場合に備えて統一 export AWS_REGION="$REGION"

AWSP は AWS_PROFILE が設定されている時だけ --profile default に展開され、未設定なら空文字になります。
これで「–profile に空が渡ってエラー」問題を回避できます。

2.1 .env 運用（おすすめ）

# rag-proto/.env などに保存（例） cat > .env <<'EOF' AOSS_ENDPOINT=https://<後で取得するdata endpoint> AOSS_INDEX=itcometrueacademy-dev-docs AWS_REGION=ap-northeast-1 AWS_PROFILE=default REGION=ap-northeast-1 PROJECT=itcometrueacademy ENV=dev COLLECTION_NAME=itcometrueacademy-dev EOF # 読み込み（値にスペースがあっても安全） set -a; source .env; set +a

3. スモークテスト（壊れていないかを最初に見る）

3.1 AWS認証主体の確認

aws sts get-caller-identity --region "$AWS_REGION" $AWSP # ここで表示される Arn が、後で DAP(データアクセスポリシー)の Principal に入る主体

3.2 AOSSコマンドの可用性

aws opensearchserverless list-collections --region "$REGION" $AWSP # まだ空でもOK。コマンドが通ればCLI準備は合格

3.3 Python依存の最低限チェック

python - <<'PY' import boto3, requests, opensearchpy from requests_aws4auth import AWS4Auth print("OK: boto3/requests/opensearchpy/requests-aws4auth import success") PY

4. 便利なスタータースクリプト（コピペOK）

4.1 01_env_setup.sh

変数をセットし、バージョンと基本疎通を一括チェック

cat > 01_env_setup.sh <<'BASH' #!/usr/bin/env bash set -euo pipefail # ===== Vars ===== export REGION="${REGION:-ap-northeast-1}" export AWS_PROFILE="${AWS_PROFILE:-default}" export PROJECT="${PROJECT:-itcometrueacademy}" export ENV="${ENV:-dev}" export COLLECTION_NAME="${COLLECTION_NAME:-${PROJECT}-${ENV}}" export INDEX_NAME="${INDEX_NAME:-${PROJECT}-${ENV}-docs}" export AWS_REGION="${AWS_REGION:-$REGION}" AWSP="${AWS_PROFILE:+--profile $AWS_PROFILE}" echo "Region : $REGION" echo "AWS_PROFILE: ${AWS_PROFILE:-<unset>}" echo "Collection : $COLLECTION_NAME" echo "Index : $INDEX_NAME" # ===== Tool checks ===== aws --version || { echo "AWS CLI not found"; exit 1; } jq --version || { echo "jq not found"; exit 1; } aws opensearchserverless help >/dev/null || { echo "CLI missing opensearchserverless"; exit 1; } # ===== Identity ===== echo "[STS] Who am I?" aws sts get-caller-identity --region "$AWS_REGION" $AWSP # ===== AOSS access ===== echo "[AOSS] Can I call list-collections?" aws opensearchserverless list-collections --region "$REGION" $AWSP | jq '.' # ===== Python deps ===== python - <<'PY' import boto3, requests, opensearchpy from requests_aws4auth import AWS4Auth print("Python deps: OK") PY echo "All green." BASH chmod +x 01_env_setup.sh

実行:

./01_env_setup.sh

5. 失敗と対処（FAQ：この回）

Q1. aws: error: argument --profile: expected one argument
原因：--profile に空文字（AWS_PROFILE 未設定のまま付けた）
対処：AWSP="${AWS_PROFILE:+--profile $AWS_PROFILE}" を使い、コマンドでは $AWSP を付ける。
（または unset AWS_PROFILE で完全に外す）

Q2. Invalid endpoint: https://sts..amazonaws.com
原因：--region が空か、AWS_REGION 未設定。
対処：export AWS_REGION="$REGION" を入れる／各コマンドに --region "$REGION" を明示。

Q3. aws: 'opensearchserverless' is not a valid command（または helpが出ない）
原因：AWS CLI が古い / v1 系。
対処：AWS CLI v2 に更新。aws --version と aws opensearchserverless help で確認。

Q4. ModuleNotFoundError: No module named 'requests_aws4auth'
原因：Python依存が未インストール／別のPythonに入れている。
対処：

which python; python -V; which pip; pip -V pip install requests-aws4auth opensearch-py boto3 requests # venvを使っているなら source venv/bin/activate 後にpip実行

Q5. .env を読み込んだのに値が反映されない / 途中で壊れた
原因：export $(grep ...) は空白や記号で壊れやすい。
対処：set -a; source .env; set +a に切替。

Q6. aws sts get-caller-identity の Arn と DAPのPrincipalが一致せず403に繋がる
原因：この回ではDAPはまだ作らないが、後工程で403の典型原因。
対処：実際に使う主体のArn（ユーザー/ロール）を aws sts get-caller-identity で確認し、DAPのPrincipalに入れる。

6. 次に進む前のチェックリスト

aws opensearchserverless help が通る
aws sts get-caller-identity が通る（Arnが意図したユーザー/ロール）
jq --version / Python依存が通る
環境変数（REGION/AWS_REGION/AWS_PROFILE/...）が意図どおり

ここまで通れば、第2回：ポリシー作成（encryption/network/data）とコレクション作成に進めます。
次回は、**失敗頻出のJSONスキーマ差分（配列ルート/オブジェクトルートの違い）や、「No matching encryption policy」**の回避も含め、完全に再現可能なスクリプトで解説します。