From 67183968c36be3465ba8bffaef995aec1ab53242 Mon Sep 17 00:00:00 2001 From: Nils Homer Date: Wed, 15 Jul 2026 19:17:57 -0400 Subject: [PATCH] docs: document the minimal IAM policy for the executor Add a "Required IAM permissions" section to docs/further.md giving the minimal core policy the executor role needs (batch:SubmitJob/DescribeJobs/ RegisterJobDefinition/DeregisterJobDefinition/TerminateJob/DescribeJobQueues/ DescribeComputeEnvironments and iam:PassRole), plus a single tags add-on (batch:TagResource, with an ecs:TagResource note for tag propagation). Each permission is tied to the feature that needs it, and the register/deregister and PassRole statements are called out as conditional (pre-existing job definitions, and only when --aws-batch-job-role is set). Cross-linked from the README. --- README.md | 2 ++ docs/further.md | 77 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 79 insertions(+) diff --git a/README.md b/README.md index 7ac7361..1ef7bd3 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,5 @@ # Snakemake executor plugin: aws-batch A Snakemake executor plugin for submitting jobs to AWS Batch. Documentation can be found in the [Snakemake plugin catalog](https://snakemake.github.io/snakemake-plugin-catalog/plugins/executor/aws-batch.html). + +For the minimal IAM policy and the tags add-on required to run the executor, see [docs/further.md — Required IAM permissions](docs/further.md#required-iam-permissions). diff --git a/docs/further.md b/docs/further.md index ea11953..bb40770 100644 --- a/docs/further.md +++ b/docs/further.md @@ -28,6 +28,83 @@ SNAKEMAKE_AWS_BATCH_REGION SNAKEMAKE_AWS_BATCH_JOB_QUEUE SNAKEMAKE_AWS_BATCH_JOB_ROLE +# Required IAM permissions + +The principal that runs Snakemake (the *executor role*) needs the following +permissions to submit and monitor jobs. The policy is split into a mandatory +core set and an add-on statement that is only needed when tags are configured. + +## Core policy (always required) + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "BatchCore", + "Effect": "Allow", + "Action": [ + "batch:SubmitJob", + "batch:DescribeJobs", + "batch:RegisterJobDefinition", + "batch:DeregisterJobDefinition", + "batch:TerminateJob", + "batch:DescribeJobQueues", + "batch:DescribeComputeEnvironments" + ], + "Resource": "*" + }, + { + "Sid": "PassJobRole", + "Effect": "Allow", + "Action": "iam:PassRole", + "Resource": "arn:aws:iam:::role/" + } + ] +} +``` + +- `batch:DescribeJobQueues` and `batch:DescribeComputeEnvironments` detect + whether a queue is backed by EC2 or Fargate so the plugin builds a compatible + job definition. They are used only by the default register-per-job path; with + a pre-existing job definition (`--aws-batch-job-definition`) they can be + omitted too. +- `batch:RegisterJobDefinition` and `batch:DeregisterJobDefinition` are only + needed when the plugin registers a job definition per job (the default). If + you use a pre-existing job definition (`--aws-batch-job-definition`), both can + be omitted — see [Pre-existing Job Definitions](#pre-existing-job-definitions). +- The `PassJobRole` statement is required in the default (register-per-job) + mode: a job role is mandatory (`--aws-batch-job-role` / + `SNAKEMAKE_AWS_BATCH_JOB_ROLE`) and is baked into every registered job + definition, so `iam:PassRole` on that role is always exercised. It can be + omitted only when you use a pre-existing job definition + (`--aws-batch-job-definition`), where the plugin neither registers a + definition nor passes a role (the pre-existing definition carries its own + role). Scope its `Resource` to that specific job role ARN. + +## Add-on: tags (`--aws-batch-tags` or `SNAKEMAKE_AWS_BATCH_JOB_TAGS`) + +```json +{ + "Sid": "BatchTagResource", + "Effect": "Allow", + "Action": [ + "batch:TagResource", + "batch:UntagResource" + ], + "Resource": "*" +} +``` + +`batch:TagResource` authorizes the tag-on-create when jobs and job definitions +are submitted with tags; without it, submission fails with `AccessDenied` +whenever tags are configured. `batch:UntagResource` is used by the executor's +startup tag-permission check, which does a tag/untag round-trip on the job queue +to surface a missing `batch:TagResource` before jobs run; without it the +throwaway preflight tag is left on the queue. Depending on your account's ECS +tagging-authorization settings you may additionally need `ecs:TagResource` on +`*`, because AWS Batch propagates tags to the ECS resources it manages. + # Rule-Specific Container Images By default, all jobs use the global container image specified via `--container-image`. However, you can specify a different container image for individual rules using the `aws_batch_container_image` resource parameter: