# IAM policy: start and stop EC2 instances by tag

IAM policy examples · Updated 17 November 2026

**Short answer:** Allow ec2:StartInstances, ec2:StopInstances and ec2:RebootInstances on instance ARNs with a condition on aws:ResourceTag, allow ec2:DescribeInstances on "*" (it has no resource-level permissions), and deny ec2:CreateTags and ec2:DeleteTags on that tag key so users can't retag other instances into scope.

## The policy

```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "StartStopTeamInstances",
      "Effect": "Allow",
      "Action": [
        "ec2:StartInstances",
        "ec2:StopInstances",
        "ec2:RebootInstances"
      ],
      "Resource": "arn:aws:ec2:eu-west-2:123456789012:instance/*",
      "Condition": {
        "StringEquals": {
          "aws:ResourceTag/Team": "${aws:PrincipalTag/Team}"
        }
      }
    },
    {
      "Sid": "SeeInstances",
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeInstances",
        "ec2:DescribeInstanceStatus"
      ],
      "Resource": "*"
    },
    {
      "Sid": "NoRetaggingTeam",
      "Effect": "Deny",
      "Action": [
        "ec2:CreateTags",
        "ec2:DeleteTags"
      ],
      "Resource": "*",
      "Condition": {
        "ForAnyValue:StringEquals": {
          "aws:TagKeys": [
            "Team"
          ]
        }
      }
    }
  ]
}
```

## How it works

- **StartStopTeamInstances**: the instance's `Team` tag must equal the caller's own `Team` tag. Tag the IAM role, user, or (with IAM Identity Center) pass it as a session tag. One policy then serves every team. For a fixed value, use `"aws:ResourceTag/Team": "analytics"`.
- **SeeInstances**: `DescribeInstances` doesn't support resource-level permissions, so everyone with this policy can see all instances in the account. They just can't act on them.
- **NoRetaggingTeam**: without it, a user with tagging rights elsewhere could add `Team=analytics` to a production instance and then stop it.

Leave out `ec2:TerminateInstances`. Stop is reversible; terminate is not.

## Attach and test

```
aws iam tag-role --role-name analytics-dev --tags Key=Team,Value=analytics
aws iam put-role-policy --role-name analytics-dev \
  --policy-name start-stop-team-instances --policy-document file://start-stop.json

aws ec2 stop-instances --instance-ids i-0123456789abcdef0 --profile analytics-dev
```

An instance without the tag returns `UnauthorizedOperation` with an encoded message; [decode it](https://cloudconsole.dev/errors/unauthorizedoperation-encoded-message) to see which condition failed.

## Variations

- **Office hours only**: add `"DateGreaterThan"` / `"DateLessThan"` on `aws:CurrentTime`, though a scheduler is usually a better fit for that.
- **Allow launching tagged instances**: that needs `ec2:RunInstances` on several resource types plus `aws:RequestTag` conditions; see [ABAC with tags](https://cloudconsole.dev/iam/abac-tags).
- **Auto Scaling instances**: stopping them usually triggers a replacement. See [stop an instance in an ASG](https://cloudconsole.dev/how-to/stop-ec2-instance-in-auto-scaling-group).

## See what a user can control

Because describe calls aren't filtered, users see every instance. A filter by tag shows only the ones this policy lets them start and stop:

```
aws ec2 describe-instances \
  --filters Name=tag:Team,Values=analytics \
  --query 'Reservations[].Instances[].[InstanceId,State.Name,Tags[?Key==`Name`]|[0].Value]' \
  --output table
```

Stop and start calls are recorded in CloudTrail with the caller's identity, so anyone using this policy leaves a clear trail. If an instance stops unexpectedly, [find who stopped it](https://cloudconsole.dev/how-to/find-who-stopped-ec2-instance) from the `StopInstances` event.

## Common mistakes

- **Putting the tag condition on `DescribeInstances`**: the call fails or returns nothing, and the console shows an empty list.
- **Encrypted EBS volumes with a customer managed key**: starting the instance can fail (often with `Client.InternalError`) unless the caller may use the key, typically `kms:CreateGrant` through EC2.
- **Tag key case**: `team` and `Team` are different tag keys in conditions. Pick one convention.

## Questions

### Can I restrict ec2:DescribeInstances by tag?

No. DescribeInstances doesn't support resource-level permissions or tag conditions, so it must be allowed on "*".

### How do I stop users removing the tag that grants access?

Deny ec2:CreateTags and ec2:DeleteTags when aws:TagKeys contains that key, as in the third statement.

## When this happens away from your desk

Stopping a runaway dev instance is a classic thing to do from a phone, and a tag-scoped policy makes it safe. CloudConsole is being built to show start and stop behind a confirmation, with production guardrails on top.

[About the CloudConsole app](https://cloudconsole.dev/aws-console-app) · [Download on the App Store](https://apps.apple.com/app/cloudconsole-for-aws/id6835419710)

## Sources

- [Example IAM policies for Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ExamplePolicies_EC2.html)
- [AWS global condition context keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html)

## Related

- [aws ec2 start-instances](https://cloudconsole.dev/cli/ec2-start-instances)
- [aws ec2 stop-instances](https://cloudconsole.dev/cli/ec2-stop-instances)
- [ABAC: tag-based access control policy example](https://cloudconsole.dev/iam/abac-tags)
- [UnauthorizedOperation: You are not authorized to perform this operation. Encoded authorization failure message](https://cloudconsole.dev/errors/unauthorizedoperation-encoded-message)
- [How to stop an EC2 instance](https://cloudconsole.dev/how-to/stop-ec2-instance)
- [IAM role trust policy: examples and how it works](https://cloudconsole.dev/iam/assume-role-trust-policy)

---

Source: https://cloudconsole.dev/iam/ec2-start-stop-by-tag

CloudConsole is an independent iPhone and Android app for Amazon Web Services by Cloudconcur Ltd. It is not affiliated with Amazon Web Services.
