IaC: Terraform & CDK

Why IaC for AWS AI intermediate

Here's the failure you're trying to avoid. You spend an afternoon in the AWS console wiring up W4–W6 by hand: create the OpenSearch collection, create the IAM role, click through the Knowledge Base wizard, attach the guardrail. It works. Three weeks later a teammate needs the same setup in a staging account and asks "how did you build this?" You open the console to retrace your clicks — but you've forgotten which strength you set on the HATE filter, the exact ARN you pasted into the role, and the one checkbox you toggled at 6pm. You rebuild it from memory, it's almost the same, and now dev and staging behave subtly differently. Nobody can say why. That gap between "what I clicked" and "what actually exists" is the disease. Infrastructure as Code (IaC) is the cure.

The core idea is a mental flip. Console clicking is imperative — you issue a sequence of actions and hope you remember them. IaC is declarative — you write down the end state you want in a text file, and a tool (Terraform or CDK) figures out how to make reality match it. Think of it as the difference between giving a friend turn-by-turn driving directions from memory versus handing them the destination address and letting the GPS route them there. When the roads change, the address still works; the memorized turns don't.

Why does this matter especially for AWS AI resources, and not just any cloud thing? Two reasons that bit you in earlier chapters:

• Dependencies are tangled. A Knowledge Base can't exist until its IAM role and its OpenSearch collection exist first — the KB references both. In W4 you hit this the hard way with boto3: create things in the wrong order and the API rejects you. IaC tools read those references and build a dependency graph, so they create the role and collection before the KB automatically. You describe what connects to what; the tool derives the order.
• Reproducibility is non-negotiable. You need the same stack in dev, stage, and prod — and you need to prove it's the same. A file in Git is diffable, reviewable in a pull request, and re-appliable to a byte-identical result. A memory of clicks is none of those things.

So IaC turns your whole W4–W6 stack — KB, guardrail, OpenSearch, roles — into a single versioned, reviewable artifact. This is the same operational discipline your LLMOps chapters preached, now pointed at AWS AI. The common beginner mistake is treating IaC as "just a way to type commands in a file" — it's not; the value is that the file is the source of truth, so anything that drifts away from it (a hand-edit in the console) becomes visible and fixable rather than a silent mystery.

Terraform: guardrail + KB intermediate

Imagine you've just been handed a blank text file and told "recreate the guardrail and Knowledge Base from W6 and W4." With boto3 you'd write a Python script that calls create_guardrail, waits, calls create_knowledge_base, handles the case where the role isn't ready yet, retries… it's a program, and you own every step. Terraform flips that on its head: you don't write the steps, you write the things. That's what the file below is — a list of the two resources you want to exist, and nothing about how to build them.

The grammar is worth slowing down on because every Terraform file you ever read follows it. A resource block reads resource "<aws-type>" "<your-nickname>" { … }. The first quoted word is fixed by the provider — aws_bedrock_guardrail is a real, specific resource type that maps to a real Bedrock API. The second quoted word is a name you invent, a local handle so other parts of the file can point at this one (you'll see aws_iam_role.kb.arn do exactly that in the next lab). Think of the type as the noun ("a guardrail") and the nickname as the pronoun you'll use to refer back to it. Inside the braces, nested blocks like content_policy_config and storage_configuration are the settings — and they mirror, almost one-for-one, the request shape you sent to boto3 in earlier chapters, just written as HCL (HashiCorp Configuration Language) instead of a Python dict.

The single most important line to notice — and the reason IaC beats a hand-written script here — is role_arn = aws_iam_role.kb.arn. You are not pasting a literal ARN string; you are referencing another resource in the file. That reference is a promise: "this KB depends on that role." Terraform reads all such references before doing anything, assembles them into a dependency graph, and creates resources in the only order that can work — role and OpenSearch collection first, KB last. This is precisely the provisioning-order problem that tripped up the boto3 version in W4, and here you never hand-order a thing; the references order it for you. The common newcomer mistake is to hard-code ARNs as plain strings "to be safe" — that severs the dependency link and quietly breaks Terraform's ordering. Prefer references; let the graph work.

main.tf# main.tf — a Bedrock guardrail and a Knowledge Base, in Terraform.
resource "aws_bedrock_guardrail" "support" {
  name                      = "support-guardrail"
  blocked_input_messaging   = "I can't help with that."
  blocked_outputs_messaging = "I can't provide that."

  content_policy_config {
    filters_config {
      type            = "HATE"
      input_strength  = "HIGH"
      output_strength = "HIGH"
    }
  }
  sensitive_information_policy_config {
    pii_entities_config {
      type   = "EMAIL"
      action = "ANONYMIZE"
    }
  }
}

resource "aws_bedrockagent_knowledge_base" "docs" {
  name     = "support-docs"
  role_arn = aws_iam_role.kb.arn

  knowledge_base_configuration {
    type = "VECTOR"
    vector_knowledge_base_configuration {
      embedding_model_arn = "arn:aws:bedrock:us-east-1::foundation-model/amazon.titan-embed-text-v2:0"
    }
  }
  storage_configuration {
    type = "OPENSEARCH_SERVERLESS"
    opensearch_serverless_configuration {
      collection_arn    = aws_opensearchserverless_collection.vec.arn
      vector_index_name = "support-index"
      field_mapping {
        vector_field   = "vec"
        text_field     = "text"
        metadata_field = "meta"
      }
    }
  }
}

The IAM role (least privilege) advanced

Every breach post-mortem you'll ever read has the same sentence buried in it: "the compromised role had more permissions than it needed." Someone, under deadline, attached AdministratorAccess to a service "just to get it working," meant to tighten it later, and never did. Months later that over-broad role is the blast radius when something goes wrong. The Knowledge Base you declared above needs to touch other AWS services to do its job — and how tightly you scope that permission is the difference between a contained incident and a catastrophic one.

Here's the concept that makes it click. In AWS, a service doesn't have permissions of its own; it assumes a role — think of a role as a lanyard-badge the KB clips on before walking into the building. The badge answers two separate questions, and confusing them is the classic beginner error. The trust policy (assume_role_policy) answers "who is allowed to wear this badge?" — here, only the bedrock.amazonaws.com service, nobody else. The permission policy (the aws_iam_role_policy) answers a completely different question: "once you're wearing it, what doors does it open?" Who versus what. Keep those two straight and IAM stops being mysterious.

The principle governing the second question is least privilege: grant exactly the abilities the resource needs to function, and not one more. Notice the discipline in the lab below — three statements, each pinned to a real need the KB has:

• Read the documents it indexes (s3:GetObject, s3:ListBucket) — and scoped to the one bucket, not all of S3.
• Call the embedding model that turns text into vectors (bedrock:InvokeModel) — scoped to the specific Titan model ARN.
• Write into the vector store (aoss:APIAccessAll for OpenSearch Serverless).

What's absent is the whole point: there is no "allow everything" statement, no wildcard on actions. If this KB were later coerced — by a bug or an attacker — into trying to delete an S3 bucket or invoke a different model, AWS would simply refuse, because that action was never granted. The jsonencode({ … }) wrapper is just plumbing: IAM policies are JSON documents, and it converts the readable HCL object into the JSON text AWS's API expects. When you review a role in a real security audit, your eye should go straight to two things — does the trust policy name a single expected principal, and does every permission trace back to a stated need? Anything you can't justify is a finding.

iam.tf# The KB's execution role: read the S3 data source, use the embeddings
# model, and write to the OpenSearch collection — nothing more.
resource "aws_iam_role" "kb" {
  name = "bedrock-kb-role"
  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect    = "Allow"
      Principal = { Service = "bedrock.amazonaws.com" }
      Action    = "sts:AssumeRole"
    }]
  })
}

resource "aws_iam_role_policy" "kb" {
  role = aws_iam_role.kb.id
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      { Effect = "Allow", Action = ["s3:GetObject", "s3:ListBucket"],
        Resource = ["arn:aws:s3:::support-docs", "arn:aws:s3:::support-docs/*"] },
      { Effect = "Allow", Action = ["bedrock:InvokeModel"],
        Resource = "arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0" },
      { Effect = "Allow", Action = ["aoss:APIAccessAll"],
        Resource = "arn:aws:aoss:*:*:collection/*" },
    ]
  })
}

The same in CDK (Python) expert

Prefer code over HCL? CDK generates CloudFormation from Python. The resource model mirrors Terraform's; pick one per team and stay consistent.

You've just written the whole stack in HCL — so why is there a second way to do the exact same thing? Because teams don't all think in configuration files. A team that lives in Python all day often finds HCL an awkward second language: no loops they recognize, no functions, no IDE autocomplete they trust. AWS's answer is the Cloud Development Kit (CDK) — you describe your infrastructure in a real programming language, and CDK compiles that into a deployment template rather than executing it directly.

The crucial thing to understand is that CDK is not a rival cloud engine to Terraform in the way it first appears. Under the hood CDK generates CloudFormation — AWS's own native IaC format — and CloudFormation is what actually creates the resources. So the pipeline is: your Python → (via cdk synth) a CloudFormation template → (via cdk deploy) real AWS resources. Terraform, by contrast, talks to the AWS APIs itself. The practical upshot is that CDK is AWS-only and rides on CloudFormation's behavior, while Terraform is multi-cloud and keeps its own state. For an all-AWS shop, that difference rarely decides anything — the honest tie-breaker is which language your team already reads fluently.

Two vocabulary anchors will make the lab readable. A Stack is CDK's unit of deployment — one bundle of resources that gets created, updated, or torn down together (the rough analog of a Terraform root module). And the Cfn prefix you'll see on CfnGuardrail stands for CloudFormation: these are L1 constructs, the lowest-level, thinnest wrappers that map one-to-one onto the raw CloudFormation resource. That one-to-one-ness is exactly why the code below is so easy to line up against the Terraform version — the nested ContentPolicyConfigProperty and ContentFilterConfigProperty classes are just Python's way of writing the same nested content_policy_config { filters_config { … } } blocks you wrote in HCL. Same infrastructure, same fields, two dialects. The mistake to avoid is agonizing over the choice as if it were architectural; it's a team-fluency call, and the one rule that actually matters is pick one and stay consistent, because a codebase split between HCL and CDK is one nobody can reason about as a whole.

ai_stack.pyfrom aws_cdk import Stack, aws_bedrock as bedrock
from constructs import Construct

class AiStack(Stack):
    def __init__(self, scope: Construct, cid: str, **kw):
        super().__init__(scope, cid, **kw)

        bedrock.CfnGuardrail(
            self, "SupportGuardrail",
            name="support-guardrail",
            blocked_input_messaging="I can't help with that.",
            blocked_outputs_messaging="I can't provide that.",
            content_policy_config=bedrock.CfnGuardrail.ContentPolicyConfigProperty(
                filters_config=[bedrock.CfnGuardrail.ContentFilterConfigProperty(
                    type="HATE", input_strength="HIGH", output_strength="HIGH")]
            ),
        )
        # a CfnKnowledgeBase construct wires the same fields as the Terraform above

resource "aws_bedrock_guardrail" "support" {
  name                      = "support-guardrail"
  blocked_input_messaging   = "I can't help with that."
  blocked_outputs_messaging = "Response withheld by policy."

  content_policy_config {
    filters_config {
      type           = "HATE"
      input_strength = "HIGH"
      output_strength = "HIGH"
    }
  }
}

resource "aws_iam_role" "bedrock" {
  name = "bedrock-invoke-role"
  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect    = "Allow"
      Principal = { Service = "bedrock.amazonaws.com" }
      Action    = "sts:AssumeRole"
    }]
  })
}

resource "aws_iam_role_policy" "invoke" {
  role = aws_iam_role.bedrock.id
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect   = "Allow"
      Action   = "bedrock:InvokeModel"
      Resource = "arn:aws:bedrock:us-east-1::foundation-model/anthropic.claude-3-5-sonnet-20241022-v2:0"
    }]
  })
}

resource "aws_bedrockagent_knowledge_base" "kb" {
  name     = "support-kb"
  role_arn = aws_iam_role.kb.arn

  knowledge_base_configuration {
    type = "VECTOR"
    vector_knowledge_base_configuration {
      embedding_model_arn = "arn:aws:bedrock:us-east-1::foundation-model/amazon.titan-embed-text-v2:0"
    }
  }

  storage_configuration {
    type = "OPENSEARCH_SERVERLESS"
    opensearch_serverless_configuration {
      collection_arn    = aws_opensearchserverless_collection.kb.arn
      vector_index_name = "kb-index"
      field_mapping {
        vector_field   = "v"
        text_field     = "t"
        metadata_field = "m"
      }
    }
  }
}

from aws_cdk import Stack, aws_bedrock as bedrock
from constructs import Construct

class AiStack(Stack):
    def __init__(self, scope: Construct, cid: str, **kw):
        super().__init__(scope, cid, **kw)
        bedrock.CfnGuardrail(
            self, "SupportGuardrail",
            name="support-guardrail",
            blocked_input_messaging="I can't help with that.",
            blocked_outputs_messaging="Response withheld by policy.",
            content_policy_config=bedrock.CfnGuardrail.ContentPolicyConfigProperty(
                filters_config=[
                    bedrock.CfnGuardrail.ContentFilterConfigProperty(
                        type="HATE", input_strength="HIGH", output_strength="HIGH"),
                ],
            ),
        )

def filters_hcl(filters):
    blocks = []
    for f in filters:
        blocks.append(
            "  filters_config {\n"
            f"    type            = \"{f['type']}\"\n"
            f"    input_strength  = \"{f['in']}\"\n"
            f"    output_strength = \"{f['out']}\"\n"
            "  }")
    return "\n".join(blocks)

spec = [{"type":"HATE","in":"HIGH","out":"HIGH"},
        {"type":"VIOLENCE","in":"MEDIUM","out":"HIGH"}]
print(filters_hcl(spec))

def drift(desired, actual):
    diffs = {}
    for k, v in desired.items():
        if actual.get(k) != v:
            diffs[k] = {"desired": v, "actual": actual.get(k)}
    return diffs

desired = {"guardrail_name": "house", "hate_strength": "HIGH",
           "embedding_model": "amazon.titan-embed-text-v2:0"}
actual  = {"guardrail_name": "house", "hate_strength": "MEDIUM",  # drifted!
           "embedding_model": "amazon.titan-embed-text-v2:0"}
d = drift(desired, actual)
print(d)   # {'hate_strength': {'desired':'HIGH','actual':'MEDIUM'}}
print("drift detected" if d else "in sync")

Knowledge check check yourself