Iac Schema

Use this file for schema/shape facts; use mapping (opens in a new tab) for the substitution rules (what each setting becomes) and managed KB API (opens in a new tab) for the camelCase API field names and accepted/rejected values that the IaC properties wrap.

Reading the public docs. Read every AWS/CloudFormation and Terraform doc read-only, per safety-and-iam (opens in a new tab). AWS/CloudFormation: curl the .md endpoint. Terraform: the authoritative source of record is the HashiCorp Terraform Registry page for the AWS provider (links in §3–§4), but it is JS-rendered, so curl its plain-text twin — the provider’s raw GitHub Markdown, identical content — instead. Do not download the Terraform provider to check it (§0); if the user runs terraform providers schema -json themselves, its output wins on any conflict.

Contents

• 0. Verify the live schema before generating a template
• 1. CloudFormation — resource types and the source (VECTOR) shape
• 2. CloudFormation — the MANAGED target shape
• 3. Terraform — resource types and the source (VECTOR) shape
• 4. Terraform — the MANAGED target shape
• 5. Cross-format notes
• Common mistakes

0. Verify the live schema before generating a template — don’t trust memory

Both schemas evolve; do not rely on memory or a hardcoded enum. Before writing or updating any template, confirm the current schema with the format-appropriate read-only command, and take the accepted type/enum values and property/argument names from its output.

CloudFormation (aws cloudformation describe-type, read-only):

Terraform: do not run a local schema check. terraform providers schema -json and terraform validate need terraform init, which downloads the AWS provider (a large download) — too heavy for a migration review, and it reads the user’s global Terraform configuration. Take argument names from the documented shapes in §3–§4 (the registry’s raw GitHub Markdown, per the note above), record schema_valid: unverified for the Terraform file, show the user a diff -u of the source file against the migrated one, and give them the command to run before they deploy:

Record the verification outcome — and never upgrade an unverified shape to a verified one. The result of §0 is one of exactly three states, and it is what the Implement phase reports as schema_valid:

If terraform or the AWS CLI is not installed, the honest answer is unverified, not true. And if either live schema disagrees with this file, trust the live schema, generate from it, and update this reference with the new finding.

What the live schema cannot check. ConnectorParameters / connector_parameters is declared free-form in both formats (proof in §2), so describe-type, cfn-lint, terraform validate and --generate-cli-skeleton all accept any content inside it. That one block is validated only by the service at create time, and managed KB API (opens in a new tab) is its authority — §0 verification tells you nothing about it.

1. CloudFormation — resource types and the source (VECTOR) shape

Both VECTOR and MANAGED knowledge bases use the same two resource types (AWS::Bedrock::KnowledgeBase + AWS::Bedrock::DataSource) and are CloudFormation-deployable. Build a source (VECTOR) template with KnowledgeBaseConfiguration.Type: VECTOR + VectorKnowledgeBaseConfiguration, the discovered StorageConfiguration block, the matching data-source connector block, and the chunking/parsing config — translating camelCase API fields to PascalCase CFN properties (the CLI/JSON shapes in managed KB API (opens in a new tab) are camelCase).

• AWS::Bedrock::KnowledgeBase — https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-bedrock-knowledgebase.html (opens in a new tab)
• AWS::Bedrock::DataSource — https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-bedrock-datasource.html (opens in a new tab)

2. CloudFormation — the MANAGED target shape

Set KnowledgeBaseConfiguration.Type: MANAGED with a ManagedKnowledgeBaseConfiguration, and set the data source’s DataSourceConfiguration.Type: MANAGED_KNOWLEDGE_BASE_CONNECTOR with a ManagedKnowledgeBaseConnectorConfiguration. Omit StorageConfiguration — the managed store is auto-provisioned, and there is no StorageConfiguration on a Managed KB. Apply mapping (opens in a new tab) for the source-type substitutions and the managed runtime limits a schema-valid template must still satisfy.

⚠️ The one place CloudFormation is NOT PascalCase

CloudFormation property names are PascalCase — except inside ConnectorParameters, which is a free-form pass-through whose keys are the camelCase API names. The live schema is explicit that nothing inside it is modelled:

ConnectorParameters has no properties and no additionalProperties: false — CloudFormation passes the object through to CreateDataSource verbatim. Consequences, all verified:

• Type: S3 / Version: "1" / ConnectionConfiguration / BucketName / InclusionPrefixes inside this block are wrong. The correct keys are type, version, connectionConfiguration, bucketName, inclusionPrefixes — from managed KB API (opens in a new tab) §2/§2b.
• No tool catches the mistake. describe-type, cfn-lint, validate-template and --generate-cli-skeleton (which returns connectorParameters: {}) all pass a PascalCased blob. It fails at deploy, against the live service.
• The wrappers around it are PascalCase and are schema-checked: DeletionProtectionConfiguration and MediaExtractionConfiguration are siblings of ConnectorParameters, inside ManagedKnowledgeBaseConnectorConfiguration. Putting either on the data source’s Properties is a hard schema error (additionalProperties: false).

Canonical managed CloudFormation shape — copy this structure

For a source whose original chunking was SEMANTIC or HIERARCHICAL, omit the whole ChunkingConfiguration block — the managed default applies (see mapping (opens in a new tab)); do not translate an unsupported strategy. The same omission is required whenever the KB uses the managed embedding model, whatever the source strategy was: a chunking block is accepted only on a custom-embedding KB.

!GetAtt <kb>.KnowledgeBaseId and .KnowledgeBaseArn are the readable attributes. Name is not a GetAtt attribute — the full read-only set is KnowledgeBaseId, KnowledgeBaseArn, CreatedAt, UpdatedAt, FailureReasons, Status.

• AWS::Bedrock::KnowledgeBase — https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-bedrock-knowledgebase.html (opens in a new tab)
• AWS::Bedrock::KnowledgeBase ManagedKnowledgeBaseConfiguration — https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-properties-bedrock-knowledgebase-managedknowledgebaseconfiguration.html (opens in a new tab)
• AWS::Bedrock::DataSource — https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-bedrock-datasource.html (opens in a new tab)

Create-only properties (from the live schema) — why this is a new resource, not an update

A VECTOR KB cannot be converted to MANAGED in place. AWS::Bedrock::KnowledgeBase declares StorageConfiguration, KnowledgeBaseConfiguration/Type and KnowledgeBaseConfiguration/ManagedKnowledgeBaseConfiguration as create-only, and AWS::Bedrock::DataSource declares KnowledgeBaseId, DataSourceConfiguration/Type, VectorIngestionConfiguration/ChunkingConfiguration and .../ParsingConfiguration as create-only.

Changing any of them replaces the resource. Two consequences to state in the plan rather than discover at deploy time: the managed KB is a new resource with a new ID (so every consumer holding the old KB ID must be repointed), and for a template consumers instantiate themselves — a Service Catalog product, a shared module, a nested stack — an in-place update is impossible, so existing instances must be re-launched, not updated.

3. Terraform — resource types and the source (VECTOR) shape

The AWS Terraform provider (hashicorp/aws) models a KB with aws_bedrockagent_knowledge_base and each data source with aws_bedrockagent_data_source. Argument names are snake_case. A source (VECTOR) KB looks like:

A data source’s chunking lives under vector_ingestion_configuration { chunking_configuration { chunking_strategy = "FIXED_SIZE" fixed_size_chunking_configuration { max_tokens overlap_percentage } } }. There is no parsing_configuration to emit on managed (Smart Parsing is applied automatically). Emit a chunking_configuration block only when the KB uses a custom embedding model; on a managed-embedding KB omit it entirely (any strategy is rejected — see mapping (opens in a new tab)).

Provider docs — trusted public source (Terraform Registry), plus the curl-able twin to fetch it:

• aws_bedrockagent_knowledge_base — Terraform Registry (authoritative source of record): https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/bedrockagent_knowledge_base (opens in a new tab)
• aws_bedrockagent_data_source — Terraform Registry (authoritative source of record): https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/bedrockagent_data_source (opens in a new tab)
• Plain-text twin to curl (the Registry page is JS-rendered — this is the same content, fetchable):
  • aws_bedrockagent_knowledge_base: https://raw.githubusercontent.com/hashicorp/terraform-provider-aws/main/website/docs/r/bedrockagent_knowledge_base.html.markdown (opens in a new tab)
  • aws_bedrockagent_data_source: https://raw.githubusercontent.com/hashicorp/terraform-provider-aws/main/website/docs/r/bedrockagent_data_source.html.markdown (opens in a new tab)

4. Terraform — the MANAGED target shape

The provider supports the managed KB directly in recent hashicorp/aws versions: in the provider schema aws_bedrockagent_knowledge_base.knowledge_base_configuration exposes managed_knowledge_base_configuration and aws_bedrockagent_data_source.data_source_configuration exposes managed_knowledge_base_connector_configuration. Read the first version that adds these blocks from the provider’s CHANGELOG (https://github.com/hashicorp/terraform-provider-aws/blob/main/CHANGELOG.md, search managed_knowledge_base) and say that minimum version in the output — older provider versions lack it. Suggest terraform fmt alongside terraform validate to the user. The agent does not check the installed version (§0): the shape is unverified, and the user’s own terraform validate is what confirms it.

managed_knowledge_base_configuration accepts exactly: embedding_model_arn, embedding_model_type, a nested embedding_model_configuration { bedrock_embedding_model_configuration { dimensions, embedding_data_type, audio { … }, video { … } } }, and server_side_encryption_configuration { kms_key_arn }. There is no storage_configuration inside it.

Managed KB — type = "MANAGED" with a managed_knowledge_base_configuration block, and no storage_configuration (auto-provisioned). embedding_model_type = "MANAGED" is the service-managed model and keeps the managed reranker. Carry the source KB’s CMK forward in server_side_encryption_configuration.kms_key_arn (see managed KB API (opens in a new tab) “Encryption at rest”); omit that block only when the customer accepts the AWS-owned default, and never silently drop a CMK the source KB was using:

Bring-your-own embedding uses embedding_model_type = "CUSTOM" with embedding_model_arn and embedding_model_configuration { bedrock_embedding_model_configuration { dimensions = <MANAGED_DIMENSION> } } (the managed dimension / FLOAT32 only, per the create page; CUSTOM disables the managed reranker — see mapping (opens in a new tab)).

Managed data source — type = "MANAGED_KNOWLEDGE_BASE_CONNECTOR" with a managed_knowledge_base_connector_configuration block. In the provider schema connector_parameters is typed "string", not a block or a map — so jsonencode({...}) is mandatory, not a style choice, and its keys are the API camelCase names (type, version, connectionConfiguration, aclEnabled, filterConfiguration, secretArn, siteUrls, …) exactly as documented in managed KB API (opens in a new tab), embedded as JSON inside the snake_case HCL.

The other two members of managed_knowledge_base_connector_configuration are nested HCL blocks, siblings of connector_parameters — not keys inside the jsonencode:

Putting deletionProtectionConfiguration inside the jsonencode blob is a silent failure: the provider accepts the string, and the deletion-protection setting is never applied.

Auth connectors (SharePoint/Confluence/OneDrive) set their fields inside the same jsonencode connectionConfiguration / dataEntityConfiguration objects (secretArn, tenantId, authType, siteUrls as a list, certificateS3Path, …) exactly as in managed KB API (opens in a new tab) §2b — the secret is referenced by ARN only. name and knowledge_base_configuration force a new resource (create-only), consistent with the CFN create-only note.

5. Cross-format notes

• Same resources, two encodings. The field names differ (CFN PascalCase; Terraform snake_case HCL), but the values, enums, and managed rules are identical and come from managed KB API (opens in a new tab) + mapping (opens in a new tab). Never hand-write a shape from memory in either format — verify with §0.
• The connector body is the one part that is byte-identical in both formats, because both ConnectorParameters and connector_parameters are free-form pass-throughs carrying the same camelCase API object. The surrounding convention never applies inside it.
• MANAGED is create-only in both. A VECTOR KB is never converted in place; the managed KB is a new resource (a new logical ID / resource address).
• The managed store is never declared. Omit CFN StorageConfiguration / Terraform storage_configuration on a managed KB.
• Scale limits are quotas, not schema. Data sources per KB and KBs per account per Region differ between self-managed and managed; read both live from Service Quotas (mapping (opens in a new tab) §4) before execution. Preserve topology by default; consolidation is an optional improvement.

Common mistakes

• PascalCasing the connector body. The most common translation error on this path: it looks correct, every offline validator (describe-type, cfn-lint, terraform validate, --generate-cli-skeleton) accepts it, and only the live service rejects it at create time. Inside ConnectorParameters / connector_parameters, keys are camelCase API names.
• Treating Terraform connector_parameters as a block/map. It is typed string; jsonencode({...}) is mandatory.
• Putting deletion_protection_configuration / media_extraction_configuration inside the jsonencode blob. They are sibling HCL blocks (Terraform) / PascalCase siblings (CFN); nesting them in the connector body is a silent no-op.
• Declaring StorageConfiguration on a managed KB; translating a SEMANTIC/HIERARCHICAL chunking strategy instead of omitting chunkingConfiguration; or emitting any chunkingConfiguration (even FIXED_SIZE/NONE) on a managed-embedding KB — it is rejected with “A chunking strategy cannot be specified with a managed embedding model”; omit the block unless the KB uses a custom embedding model.
• Reporting an unverified shape as verified. If §0 could not run, say which command was unavailable; the template is documented-shape only.
• Expecting an in-place VECTOR→MANAGED update. Create-only properties force resource replacement: a new KB ID and re-launched instances for consumer-instantiated templates.

Source

• references/bedrock-kb-migration/iac-schema.md(opens in a new tab)
• Raw file(opens in a new tab)
• aws/agent-toolkit-for-aws(opens in a new tab)