What the agent does
Since version 4 of the AWS provider, an aws_s3_bucket resource is meant to describe the bucket and little else. Settings that used to be nested inside it, such as versioning, lifecycle_rule, acl and server_side_encryption_configuration, each have a resource of their own. A configuration written the old way still validates on current providers, with Warning: Argument is deprecated and a line such as versioning is deprecated. Use the aws_s3_bucket_versioning resource instead. On provider 4.0.0 through 4.8.0 the same block was a hard failure, Error: Value for unconfigurable attribute, with Can't configure a value for "acl": its value will be decided automatically, and that is the message many people search for after an unplanned provider upgrade.
monterail/terraform-bootstrap-example contains the pattern in the place where a mistake costs most. modules/backend/main.tf creates the S3 bucket that stores Terraform's own remote state, and the aws_s3_bucket.terraform_state block sets acl = "private", a versioning block with enabled = true, a lifecycle_rule named expire that removes noncurrent versions after 90 days, and a server_side_encryption_configuration using the KMS key declared above it. No file in the repository has a required_providers block. The provider "aws" block in setup/main.tf, which base/main.tf reaches through a symlink, sets only profile and region, so terraform init installs the newest AWS provider. The README says the approach was tested against Terraform v0.12.24.
The agent starts by measuring. It copies the bucket block into a scratch configuration and runs terraform validate against several provider versions. With Terraform 1.9.8 the block gives four deprecation warnings on provider 3.76.1, four errors on 4.0.0 and on 4.8.0, warnings again from 4.9.0, and three warnings on 6.72.0: for lifecycle_rule, versioning and acl. It then rewrites the module. versioning becomes an aws_s3_bucket_versioning resource with versioning_configuration { status = "Enabled" }. The lifecycle rule becomes aws_s3_bucket_lifecycle_configuration, where enabled = true turns into status = "Enabled" and days into noncurrent_days. Encryption moves to aws_s3_bucket_server_side_encryption_configuration. For acl = "private" the agent removes the argument and adds no ACL resource, since private is what a bucket has without one, and it writes that decision down for the reviewer.
Rewriting is half the job; the state is the other half. The bucket already exists with these settings, so the agent adds an import block for each new resource, keyed by the bucket name, and the first plan adopts the existing configuration instead of proposing to create it. Terraform accepts import blocks only in a root module, so they go in setup/main.tf with addresses that begin module.backend, not in the module itself. It adds a required_providers entry with a lower bound, because a module with no constraint is how the surprise upgrade happened. Then it runs terraform init and terraform validate and confirms the result is clean on the newest provider. It cannot run terraform plan without your AWS credentials and state, and it says so. The plan is the reviewer's step, and the pull request states exactly what that plan should show.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "terraform validate reports \"Warning: Argument is deprecated\" on aws_s3_bucket resources, with messages such as \"versioning is deprecated. Use the aws_s3_bucket_versioning resource instead.\" (on AWS provider 4.0 to 4.8 the same configuration fails with \"Error: Value for unconfigurable attribute\" and \"Can't configure a value for 'acl': its value will be decided automatically\"). Find every aws_s3_bucket resource in the repository, including inside modules, and list each deprecated inline argument or block it uses: acl, versioning, lifecycle_rule, server_side_encryption_configuration, logging, website, cors_rule, replication_configuration, grant, object_lock_configuration, acceleration_status, request_payer and policy. Record the Terraform and AWS provider versions the repository pins, or that it pins none. Run terraform init and terraform validate with the newest AWS provider and keep the warnings. Move each inline setting into its standalone resource (aws_s3_bucket_versioning, aws_s3_bucket_lifecycle_configuration, aws_s3_bucket_server_side_encryption_configuration and so on), translating renamed fields exactly and preserving the behaviour of every rule. For acl: if the value is private, remove it and say why; for any other value add aws_s3_bucket_acl together with the aws_s3_bucket_ownership_controls it needs, and flag it for review. For every new resource add an import block so existing buckets are adopted, not recreated; Terraform rejects import blocks inside child modules, so put them in each root module that calls the module, addressed through the module; if the bucket name is a variable, use it in the import id. Add a required_providers block with a minimum AWS provider version if none exists, and do not add an upper bound. Do not rename or replace any bucket, do not run terraform apply, and do not change unrelated resources. Run terraform fmt and terraform validate and show the output is clean. You have no cloud credentials, so do not attempt terraform plan; instead write in the pull request what a correct plan should contain and which lines would indicate a problem. List anything else in the configuration that current Terraform rejects or deprecates, without fixing it.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
A pull request in which the bucket resource shrinks to its name and tags, and three or four new resources appear beside it, each with an import block. The description has a mapping table: every inline argument that was removed, the resource and field that replaced it, and the value carried over. Renamed fields are called out, because enabled = true becoming status = "Enabled" is where a careless rewrite drops a rule.
The validation output is included for the provider versions tested, before and after. After the change, terraform validate on the newest provider reports that the configuration is valid, with no warnings for the bucket. The description then states what was not done: no plan and no apply, since the sandbox holds no credentials for your account.
So the reviewer's task is specific. Run terraform plan in each workspace that uses the module and read it against the description. A correct plan imports the new resources and proposes no change to the bucket itself beyond dropping attributes the provider now computes. Any line that would destroy or replace a bucket, or create a lifecycle configuration that differs from the old rule, is a reason to stop. For a bucket that stores state, as in the fixture, take a copy of the state file first.
Run it on every Linear issue labelled terraform-deprecation
Deprecation warnings are easy to ignore until a provider major removes the argument, so teams tend to track them as issues. An automation with a linear trigger on linear.issue.labeled, filtered to your label and created in the Project that holds the infrastructure repository, starts one run for every issue that gets the label. The issue's text is added after the automation's prompt. Write the prompt to stand alone and let the issue supply the module or directory to work on.
A scheduled check finds them before anyone files an issue. A weekly job in your CI can run terraform validate -json, look for diagnostics whose summary is Argument is deprecated, and send the request above with your API key when it finds any. Use a request_id that is a UUID v5 of the repository and the sorted list of warnings, so the same set of warnings never starts two runs.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
Why run it on Rush?
Testing a configuration against six provider versions means downloading six providers, each of them hundreds of megabytes, into a plugin directory you then have to clean up. Nobody does that on a laptop for a warning. In a sandbox the agent can install as many as the question needs, validate the old and new configuration against each, and discard the lot when the run ends.
The run is also limited in a way that suits infrastructure work. The sandbox has the repository and no cloud credentials unless you put some in the Project, so the agent can rewrite and validate but cannot apply anything to your account. What you get back is a diff, the validation output and a written expectation for the plan. The apply stays with a person.
Frequently asked questions
Is this a warning or an error?
It depends on the provider version. With the same bucket block, AWS provider 3.76.1 warns, 4.0.0 and 4.8.0 fail with Value for unconfigurable attribute, and 4.9.0 through 6.72.0 warn again. If you are seeing the error, upgrading the provider within 4.x turns it back into a warning while you do the real fix.
Will splitting the resources recreate my bucket?
It should not, and the plan is how you confirm it. The bucket resource keeps its address and name; only settings move out. With an import block for each new resource, Terraform adopts the existing versioning, lifecycle and encryption configuration instead of creating it.
Do I need aws_s3_bucket_acl for a private bucket?
Usually not. Private is the default, so removing acl = "private" changes nothing about access. New buckets are created with ACLs disabled, and adding an ACL resource to such a bucket fails unless ownership controls are changed first. The agent removes a private ACL and flags any other value for a human decision.
Can the agent run terraform plan for me?
Only if the run has credentials. A secret saved to a Project reaches every session started in that Project as an environment variable, so read-only AWS credentials stored there would let the agent plan. Without them it validates only and tells you what the plan should contain.
Why add a required_providers block?
Because a configuration with no constraint installs whatever provider is newest on the day of terraform init. That is how a module tested years ago meets a provider with different rules. A minimum version documents what the rewritten resources need, and the committed lock file fixes the exact version for everyone.