概要
SREエンジニアの高見です。最近流行りのRAG+AI、その中でも使い勝手の良いAWS Bedrock+Knowledge Baseをterraform管理したいなと思ってハマった事を解説します。
オチとしては、2025年10月末時点で、Knowledge Baseのカスタムメタデータの設定がhashicorp/awsでは対応しておらず、hashicorp/awsccにプロバイダを変えて実装したら解決しました、というお話です。
1. はじめに：やりたかったこと
Amazon Bedrock Knowledge Base (KB) は、RAG（検索拡張生成）を手軽に実装できる強力な機能です。このKBの回答精度や検索の柔軟性を高めるために、データソースにカスタムメタデータを付与する機能があります。
私たちのチームでは、AWSリソースの管理をTerraformの hashicorp/aws プロバイダで統一していました。当然、今回のBedrock KBもTerraformで管理しようとしました。
具体的には、以下の構成を目指しました。
- データベース: Aurora PostgreSQL Serverless (Vector DBとして利用)
- データソース: S3バケットに配置したCSVファイル
- メタデータ: hoge.csv.metadata.json のようなファイルでCSVの各行にメタ情報を付与
カスタムメタデータとは？
カスタムメタデータを使うと、S3上のデータ（例: hoge.csv）に対して、以下のようなメタ情報ファイル（hoge.csv.metadata.json）を紐付けられます。
hoge.csv.metadata.json (サンプル)
{
"version": "1.0",
"metadataFileMaps": {
"hoge.csv": {
"metadataAttributes": {
"category": {
"type": "string"
},
"document_owner": {
"type": "string"
},
"last_updated": {
"type": "date"
}
},
"chunkingConfiguration": {
"chunkingStrategy": "FIXED_SIZE",
"fixedSizeChunkingConfiguration": {
"maxTokens": 300,
"overlapPercentage": 20
}
}
}
}
}
これにより、KBへの問い合わせ時に「categoryが 'finance' のものだけ検索する」といった高度なフィルタリングが可能になります。
当初は、AWSの公式ドキュメントや記事を参考に、hashicorp/awsプロバイダ (aws_bedrockagent_knowledge_base) を使って構築を進めました。
2. 発生した問題：KBのデータ同期エラー
terraform apply でKBやAurora DBのリソース作成自体は成功しました。しかし、肝心のデータをS3からKBに取り込む「データソースの同期 (Sync)」が失敗する事態に見舞われました。
AWSコンソールから手動で [Sync] ボタンを押しても、CloudWatch Logsには不可解なエラーが出力されるばかりでした。
実際に出力されたエラー
Encountered error: The vector database encountered an error while processing the request: Duplicate parameter id (Service: RdsData, Status Code: 400, Request ID: hogehogehoge) (SDK Attempt Count: 1). Issue occurred while processing file: s3://hoge-bucket/foo.csv. Call to Amazon RDS Vector Database did not succeed.
idが重複すると、これは手動でBedrockを立ち上げたときには出なかったエラーです。
Encountered error: The vector database encountered an error while processing the request: ERROR: column "sequence_num" is of type integer but expression is of type text; Hint: You will need to rewrite or cast the expression.; Position: 999; SQLState: 9999 (Service: RdsData, Status Code: 400, Request ID: hogehogehoge) (SDK Attempt Count: 1). Issue occurred while processing file: s3://hoge-bucket/foo.csv. Call to Amazon RDS Vector Database did not succeed.
idをtest_idに変えると別のエラーが出ます。なんかカラムがおかしいぞ、と。
エラーメッセージからは、DBのスキーマやリレーション、型が期待通りでないらしいことは分かりましたが、原因の特定は困難でした。
3. 原因調査：hashicorp/awsプロバイダの限界
何が間違っているのかを切り分けるため、一度Terraformを離れ、AWSコンソールから手動で、カスタムメタデータを有効にしたKBを作成してみました。
そして、Terraformが作成したAurora DBのスキーマと、手動で作成したAurora DBのスキーマを見比べたところ、決定的な違いを発見しました。
手動作成（成功例）: DBのテーブル内にcustommetadataというカラムが自動生成されている。
Terraform作成（失敗例）: custommetadataカラムが存在しない。
で、hashicorp/aws プロバイダ (aws_bedrockagent_knowledge_base)内で、カスタムメタデータの設定を有効化しようとすると、terraform planで「そんなものはない」とエラーになってしまいました。
リソースの引数を調べてもそれらしい設定は見当たらず、最終的にGitHub Issueを発見しました。
このIssueにより、2025年10月時点でhashicorp/aws プロバイダがカスタムメタデータ設定に未対応であることが確定しました。
4. 失敗した対応策：CLIでの後付け更新
「Terraformでリソースを作った後、AWS CLIで設定変更すればよいのでは？」と考え、以下の策を試しました。
- TerraformでKBを作成（カスタムメタデータ設定なし）。
- AWS CLIの update-knowledge-base コマンドで storageConfiguration を変更しようとする。
しかし、これは無情なエラーで失敗しました。
Error: An error occurred (ValidationException) when calling the UpdateKnowledgeBase operation: You cannot modify the storage configuration of the Vector knowledge base once created.
KBの storageConfiguration（ストレージ設定）は、一度作成すると変更できないイミュータブル (immutable) な設定だったのです。
5. 最終的な解決策：awsccプロバイダの採用
AIと相談したところ、hashicorp/awsがダメなら、awscc (AWS Cloud Control)と使えば良いじゃんという話が来ました。
awsccは、AWS CloudFormationの仕様とほぼ1:1で対応するAWS公式のTerraformプロバイダであり、hashicorp/aws よりも新機能への追随が早い傾向があります。
awsccのawscc_bedrockagent_knowledge_baseリソースのドキュメントをAIに調べさせると、storage_configuration.vector_knowledge_base_configuration内に、まさに求めていたcustom_metadata_configuration引数が存在しました！
既存の hashicorp/aws で管理しているリソース（VPC, Aurora DB本体など）はそのままに、Bedrock KBのリソース定義だけを awscc に置き換える「ハイブリッド構成」を採用しました。
1.プロバイダの定義 (versions.tf など)
hashicorp/aws に加えて awscc を追加します。
terraform {
required_providers {
aws = {
source = "hashicorp/aws"
version = "~> 5.0"
}
awscc = {
source = "hashicorp/awscc"
version = "~> 0.70" # バージョンは適宜最新を確認してください
}
}
}
provider "aws" {
region = "us-east-1" # Bedrockが利用可能なリージョン
}
provider "awscc" {
region = "us-east-1"
}
2. Bedrock KBのリソース定義 (bedrock.tf など)
aws_bedrockagent_knowledge_base の代わりに awscc_bedrockagent_knowledge_base を使います。サンプルですが、こんな具合です。
# -----------------------------------------------
# Knowledge Base
# -----------------------------------------------
resource "awscc_bedrock_knowledge_base" "main" {
name = "${local.kb_name_prefix}-knowledge-base"
description = var.description
role_arn = aws_iam_role.knowledge_base.arn
knowledge_base_configuration = {
type = "VECTOR"
vector_knowledge_base_configuration = {
embedding_model_arn = local.embedding_model_arn
}
}
storage_configuration = {
type = "RDS"
rds_configuration = {
credentials_secret_arn = var.aurora_secret_arn
database_name = var.aurora_database_name
resource_arn = var.aurora_cluster_arn
table_name = local.bedrock_table_fqn
field_mapping = {
vector_field = "embedding"
text_field = "chunks"
metadata_field = "metadata"
primary_key_field = "id"
custom_metadata_field = "custommetadata" # この設定が重要！同様の設定はhashicorp/awsからだと設定不可だった
}
}
}
tags = var.tags
}
aws_bedrock_knowledge_baseもawscc_bedrock_knowledge_baseも似たような記述なのですが、custom_metadata_field = "custommetadata"が設定出来る/出来ないかがクリティカルでした。
結果：成功
この構成でterraform applyを実行したところ、custommetadataカラムを含むDBスキーマが正しく作成されました。
その後、AWSコンソールから対象データソースの [Sync] ボタンを手動で実行したところ、今度はエラーなくデータ同期が完了しました。
6. まとめ
- hashicorp/aws プロバイダは非常に強力ですが、一部の詳細な機能（今回は、カスタムメタデータ）への対応が遅れるケースがあります。
- storageConfiguration のように後から変更不可能な設定でTerraformが未対応だと、致命的な手詰まりになります。
- このような場合、CloudFormationに準拠した awsccプロバイダが強力な代替手段となります。
- すべてのリソースを awsccに置き換える必要はなく、今回のように未対応のリソースだけをawscc で管理する「ハイブリッド構成」は、現実的で有効な戦略です。
TerraformでBedrock KBのカスタムメタデータが使えずに困っている方の助けになれば幸いです。
Discussion