water park

Course 2 · after Fountain: The IAM repo · lesson 15 (I15)

Adopt in place

Properties
I Honor the lower layer, XII Adopt in place
Goal
Make three things the way a console would, a role, a bucket and a security group with an open port, and watch the drift watch not see them. Then bring each under management with an import block and a resource block reviewed out of generated config, prove with a script that the only thing the apply changes is the tags the estate puts on what it owns, watch the rule pack refuse the adopted role the same way it would refuse a written one, back the group out with a removed block and find it still in the account, and say what walking away costs, which is nothing.
Done when
access/scripts/adopt-check reports three adoptions each changing nothing but the estate’s own tags and fails one whose file misstates the account by naming the attribute, the apply reports 3 imported, 0 added, 3 changed and the replan exits 0, aws iam list-role-tags on legacy-reporter shows managed_by, repo and env beside the one tag it had, access/scripts/check lint fails on the adopted role’s missing boundary and owner tag and warns on the group’s open port, and after a removed block is applied legacy-ssh is still in the account and the replan still exits 0.
Restart from
checkpoint/i11 (the lesson whose checkpoint to reload if this one breaks)
Mode
· about 35 min

Run with an agent

Paste this to your agent.

curl -fsSL https://raw.githubusercontent.com/INTENTIUS/waterpark/main/skills/i15-adopt-in-place/SKILL.md and follow that skill with me, step by step. Confirm with me before you install or write anything.

The skill is skills/i15-adopt-in-place/SKILL.md (on GitHub). Installable too, with npx skills add INTENTIUS/waterpark, or by copying skills/i15-adopt-in-place into ~/.claude/skills/, or as a Fountain agent skill from INTENTIUS/waterpark.

Do · 35 min

hands-on

You need: a water park checkout with the tags fetched, Docker running, or the Start-here stack up, whose Floci this lesson can use as it is, the patched Floci image ghcr.io/lex00/floci:iam-boundary, terraform 1.9 or newer, tflint from terraform-linters/tap/tflint, jq, just access-init run once per clone, lesson 11 finished or at least read.

Context

Do

Fourteen lessons wrote an estate from nothing. This one starts from what is already there, which is where every real estate starts.

  1. Start from the checkpoint lesson 11 left, get an emulator, and apply central and then the satellite.

    git fetch origin --tags
    git worktree add ../waterpark-i15 checkpoint/i11
    cd ../waterpark-i15
    just access-init
    

    If the Start-here stack is up, its Floci already answers on port 4566 and this lesson can use it as it is, so skip the docker run below. It runs with IAM enforcement off, which this lesson never needs, and it holds whatever earlier Fountain lessons left, which is nothing this lesson names. If the stack is down, start the container the earlier lessons started.

    docker run -d --name wp-i15-floci -p 4566:4566 \
      -e FLOCI_SERVICES_IAM_ENFORCEMENT_ENABLED=true \
      ghcr.io/lex00/floci:iam-boundary
    

    Either way, then

    curl -s --retry 15 --retry-all-errors --retry-delay 1 \
      -o /dev/null -w '%{http_code}\n' http://localhost:4566/
    
    terraform -chdir=access/envs/prod init
    terraform -chdir=access/envs/prod apply -auto-approve
    terraform -chdir=access/satellites/waterpark-runner init
    terraform -chdir=access/satellites/waterpark-runner apply -auto-approve
    

    200, then Resources: 18 added and 8 added.

  2. Make three things the way a console would. A role for a reporting job somebody set up in 2024, a bucket it writes to, and a security group with port 22 open to the world. None of them goes through a pull request, and that is the point.

    export AWS_ACCESS_KEY_ID=test AWS_SECRET_ACCESS_KEY=test AWS_DEFAULT_REGION=us-east-1
    
    aws --endpoint-url http://localhost:4566 iam create-role --role-name legacy-reporter \
      --description "Made in the console in 2024." \
      --assume-role-policy-document '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":{"Service":"lambda.amazonaws.com"},"Action":"sts:AssumeRole"}]}' \
      --tags Key=team,Value=analytics --query Role.Arn --output text
    
    aws --endpoint-url http://localhost:4566 s3 mb s3://legacy-uploads
    
    SG=$(aws --endpoint-url http://localhost:4566 ec2 create-security-group \
      --group-name legacy-ssh --description "ssh from anywhere" --query GroupId --output text)
    aws --endpoint-url http://localhost:4566 ec2 authorize-security-group-ingress \
      --group-id $SG --protocol tcp --port 22 --cidr 0.0.0.0/0 --query Return
    echo $SG
    

    The ARN, make_bucket: legacy-uploads, true, and a group id like sg-4ebfc472f9999f8c2. Keep the id, two files below need it. The ingress call takes the id rather than the name, because the emulator does not resolve a group by name on that call.

    Now ask the watch.

    access/scripts/drift | tail -1
    

    every watched root matches the account. Three things the estate knows nothing about, and the watch is right to say nothing, because it compares what the repo declares against what the account holds and the repo declares none of them. Lesson 7 called this the asymmetry. Restoring is automatic, adopting is a file, and here are three files to write.

  3. Adopt the role. Give the provider its first ec2 endpoint while you are in envs/prod, since the group needs it. Open access/envs/prod/provider.tf and add one line inside the content block after s3.

        content {
          iam = endpoints.value
          sts = endpoints.value
          s3  = endpoints.value
          ec2 = endpoints.value
        }
    

    Then write access/envs/prod/iam_role.legacy_reporter.tf with only the import block in it, and let Terraform draft the rest.

    import {
      to = aws_iam_role.legacy_reporter
      id = "legacy-reporter"
    }
    
    terraform -chdir=access/envs/prod init
    terraform -chdir=access/envs/prod plan -generate-config-out=generated.tf
    cat access/envs/prod/generated.tf
    

    Plan: 1 to import, 0 to add, 1 to change, 0 to destroy., and the draft, under a two-line header asking you to review it.

    # __generated__ by Terraform from "legacy-reporter"
    resource "aws_iam_role" "legacy_reporter" {
      assume_role_policy = jsonencode({
        Statement = [{
          Action = "sts:AssumeRole"
          Effect = "Allow"
          Principal = {
            Service = "lambda.amazonaws.com"
          }
        }]
        Version = "2012-10-17"
      })
      description           = "Made in the console in 2024."
      force_detach_policies = false
      max_session_duration  = 3600
      name                  = "legacy-reporter"
      path                  = "/"
      permissions_boundary  = null
      tags = {
        team = "analytics"
      }
      tags_all = {
        team = "analytics"
      }
    }
    

    Read it against the role you made. The trust policy, the description, the name and the tag are yours. force_detach_policies, max_session_duration and path are the provider’s defaults written out, permissions_boundary = null is an absence spelled as a value, and tags_all is what the provider computes and must never be declared. The review is dropping all of that. Replace the file with this, which is the import block and what the account actually holds.

    # Adopted in lesson 15. This role existed before the repo did, made in a
    # console, and the import block below is what brought it under management.
    # Everything under the block is what the account held on the day, reviewed
    # out of terraform plan -generate-config-out and nothing else.
    import {
      to = aws_iam_role.legacy_reporter
      id = "legacy-reporter"
    }
    
    resource "aws_iam_role" "legacy_reporter" {
      name        = "legacy-reporter"
      description = "Made in the console in 2024."
    
      assume_role_policy = jsonencode({
        Version = "2012-10-17"
        Statement = [{
          Effect    = "Allow"
          Principal = { Service = "lambda.amazonaws.com" }
          Action    = "sts:AssumeRole"
        }]
      })
    
      tags = {
        team = "analytics"
      }
    }
    
    rm access/envs/prod/generated.tf
    

    generated.tf is in .gitignore already, because a draft is never the file.

  4. Bring in the check, and run it before and after breaking the file on purpose.

    git checkout checkpoint/i15 -- \
      access/scripts/adopt-check \
      access/.tflint.d/policies/security.rego \
      access/tests/fixtures/no-open-ingress
    access/scripts/adopt-check
    
    adopt check, access/envs/prod
    
      [ok] aws_iam_role.legacy_reporter  from legacy-reporter
          the estate adds its tags: env, managed_by, repo
    
      1 adoption(s), and none changes anything but the estate's own tags.
    

    That is the plan, read for you. One import, and the one change is three tags the provider’s default_tags put on everything the estate owns, which is the estate’s mark and nothing the role had. Now misstate the account. Change 2024 to 2023 in the description, and run it again.

      [FAIL] aws_iam_role.legacy_reporter  from legacy-reporter
          the estate adds its tags: env, managed_by, repo
          the file differs from the account on: description
          fix the file, because an apply would edit the account
    
      1 of 1 adoption(s) would change the account. Adopt in place means the file says what is there.
    

    Exit 2. An import whose file is wrong is not an adoption, it is an edit nobody asked for, dressed as one, and the check names the attribute so you fix the file rather than the account. Put 2024 back, see [ok] again, and apply.

    terraform -chdir=access/envs/prod apply -auto-approve
    terraform -chdir=access/envs/prod plan -detailed-exitcode
    echo $?
    aws --endpoint-url http://localhost:4566 iam list-role-tags --role-name legacy-reporter \
      --query 'Tags[].[Key,Value]' --output text
    

    aws_iam_role.legacy_reporter: Import complete [id=legacy-reporter], Resources: 1 imported, 0 added, 1 changed, 0 destroyed., then 0, then four tags, team analytics as it was and the estate’s three beside it. The role’s trust, name and description did not move, and the account says so. Run the check once more and the role’s row reads already in state, because an import that has landed makes no importing change in the plan and the check reads the block off the file instead.

  5. Adopt the other two, in one apply. Write access/envs/prod/s3_bucket.legacy_uploads.tf.

    # Adopted in lesson 15. See iam_role.legacy_reporter.tf.
    import {
      to = aws_s3_bucket.legacy_uploads
      id = "legacy-uploads"
    }
    
    resource "aws_s3_bucket" "legacy_uploads" {
      bucket = "legacy-uploads"
    }
    

    And access/envs/prod/security_group.legacy_ssh.tf, with your group id from step 2 in the import block.

    # Adopted in lesson 15. See iam_role.legacy_reporter.tf.
    import {
      to = aws_security_group.legacy_ssh
      id = "sg-4ebfc472f9999f8c2"
    }
    
    resource "aws_security_group" "legacy_ssh" {
      name        = "legacy-ssh"
      description = "ssh from anywhere"
      vpc_id      = "vpc-default-us-east-1"
    
      ingress {
        from_port   = 22
        to_port     = 22
        protocol    = "tcp"
        cidr_blocks = ["0.0.0.0/0"]
      }
    
      egress {
        from_port   = 0
        to_port     = 0
        protocol    = "-1"
        cidr_blocks = ["0.0.0.0/0"]
      }
    }
    

    Both are the generated draft reviewed the same way, and you can prove that by running -generate-config-out again first if you like. The bucket’s draft carries bucket_namespace, force_destroy, object_lock_enabled and region, all defaults, and the group’s carries the same tags_all and region, a revoke_rules_on_delete = null, and an egress rule the account made for it. The egress stays, because the account holds it.

    access/scripts/adopt-check
    terraform -chdir=access/envs/prod apply -auto-approve
    terraform -chdir=access/envs/prod plan -detailed-exitcode
    echo $?
    

    Three [ok] rows, the role’s reading already in state and nothing changes because step 4 brought it in, the other two from their ids with the estate’s tags to add, then Resources: 2 imported, 0 added, 2 changed, and 0.

  6. Run the check stack, and read the refusal as a list.

    just access-check
    
    envs/prod/iam_role.legacy_reporter.tf:10:1: Error - aws_iam_role.legacy_reporter carries no owner tag. Add tags = { owner = local.owner }, or pass owner to modules/persona. (opa_deny_tag_owner_required)
    envs/prod/s3_bucket.legacy_uploads.tf:7:1: Error - aws_s3_bucket.legacy_uploads carries no owner tag. Add tags = { owner = local.owner }, or pass owner to modules/persona. (opa_deny_tag_owner_required)
    envs/prod/iam_role.legacy_reporter.tf:10:1: Error - aws_iam_role.legacy_reporter carries no permissions_boundary. Every role water park emits sits inside the estate boundary from access/baseline. (opa_deny_boundary_required)
    envs/prod/security_group.legacy_ssh.tf:16:19: Warning - aws_security_group.legacy_ssh opens 22 to 0.0.0.0/0 in an inline ingress block. Name the source security group, and declare the rule as its own aws_vpc_security_group_ingress_rule so it has an address a review can point at. (opa_warn_no_open_ingress)
    FAIL  tflint in access/envs/prod
    == generated CODEOWNERS
    gen-codeowners: envs/prod/iam_role.legacy_reporter.tf names no team. Add a teams list, or the file routes to nobody
    FAIL  .github/CODEOWNERS was hand edited or a principal file moved
    

    Two errors on the role, one on the bucket, a warning on the group, a principal file that routes to nobody, and check failed, 2 problem(s). Nothing about being adopted exempts a resource from the rules, and that is what one at a time is for. This list is day two. A boundary on the role, an owner on both, a source group instead of the world, and a team on the role so its review has an owner, each its own pull request with the plan showing exactly that change. The warning is new in this lesson. no-open-ingress read only the standalone rule shape until now, and the inline shape is what generated config writes, so an adopted group with an open port would have slipped past a rule written to catch it. Step 4 brought the widened rule and its fixtures in.

  7. Back the group out without destroying it. Delete its file and write access/envs/prod/removed.legacy_ssh.tf.

    rm access/envs/prod/security_group.legacy_ssh.tf
    
    # Back the group out of management without destroying it. The block is
    # applied once and then deleted from the repo, because there is nothing left
    # for it to say.
    removed {
      from = aws_security_group.legacy_ssh
    
      lifecycle {
        destroy = false
      }
    }
    
    terraform -chdir=access/envs/prod plan
    terraform -chdir=access/envs/prod apply -auto-approve
    aws --endpoint-url http://localhost:4566 ec2 describe-security-groups --group-ids $SG \
      --query 'SecurityGroups[0].GroupName' --output text
    rm access/envs/prod/removed.legacy_ssh.tf
    terraform -chdir=access/envs/prod plan -detailed-exitcode
    echo $?
    

    # aws_security_group.legacy_ssh will no longer be managed by Terraform, but will not be destroyed and Plan: 0 to add, 0 to change, 0 to destroy., then the apply, then legacy-ssh from the account, then 0 with the block gone. The group is exactly where it was, the repo has stopped claiming it, and the watch has stopped watching it. That is the reverse of step 5 and it cost the account nothing either way.

  8. Say what walking away costs.

    ls access/envs/prod/*.tf
    

    That listing is the handover. Every file is HCL the provider applies directly, the import blocks are Terraform’s own syntax, and nothing in the directory is a format this course invented. A team that stops using water park keeps the directory and drops the checks, the scripts and the workflow, and the estate is exactly as manageable as it was, which is decision 2’s whole claim and the reason there is no export bundle to build.

  9. Compare with the reference repo, then tear down. The three adopted files are yours and not the repo’s, because the resources they import exist only where your hand made them, so the compare leaves them out.

    git add -A access .github
    git diff --cached --stat checkpoint/i15 -- access .github ':!*README.md' ':!access/envs/prod/*legacy*'
    
    terraform -chdir=access/satellites/waterpark-runner destroy -auto-approve
    terraform -chdir=access/envs/prod destroy -auto-approve
    aws --endpoint-url http://localhost:4566 ec2 delete-security-group --group-id $SG
    

    Nothing printed means the provider line, the rule and the check are the reference’s. The destroy reads 20 destroyed, the estate’s eighteen and the two adopted, because legacy-reporter and legacy-uploads are managed now and that is what managed means, and it leaves legacy-ssh, because step 7 gave it back, so the last line removes it by hand. If you started your own container in step 1, docker rm -f wp-i15-floci as well.

Self-paced

The whole lesson runs on the emulator, and it runs on the Start-here stack’s Floci without enforcement, because nothing here is a refusal by IAM. Every import, every plan and the removed block behave on Floci as they do on a real account, which plan phase 0 verified before any IAM lesson was written and this lesson leans on.

Two things a real account adds. Real resources carry more than a console fixture does, so the generated draft is longer and the review is more work, and that is the honest cost of one at a time. And on a real account the three default tags land on resources other teams can see, which is why adopting is a pull request somebody reviews rather than a script somebody runs.

The adopted files never join the reference tree. The compare excludes them and the checkpoint carries none, because a checked-in import of a resource that exists only on one laptop would fail every other laptop’s plan and the CI job’s too.

Live

Twenty minutes, and the room needs steps 2, 4 and 6.

Open on step 2 with the three console fixtures already made, and run drift in front of the room. The line to say is that the watch is right to say nothing, because it watches what the repo declares and the repo does not know these exist. Then step 4 whole, with the 2023 edit typed live. The check names the attribute, and the line to say is that an import whose file is wrong is an edit nobody asked for, and the only defence is a check that reads the plan rather than a reviewer who trusts the word adopt.

Then step 6, and let the room read the four lines. The honesty line is that adopting a resource earns it nothing, that the checks fail it exactly as they would fail a new file, and that the failing list is the work, one pull request each, which is the only way a real estate has ever been brought to conform.

Live, the same files import from a real sandbox account, the generated drafts are longer, and the room can watch a role that predates the repo acquire the repo’s tags and nothing else.

Further reading