AWS Diagram Guide

Showing IAM in an AWS architecture diagram without drowning it

By the engineer who builds Datadef, from client work on data platforms · Reviewed August 21, 2026

IAM is the one AWS service that touches every account, every resource, and every call, which is exactly why it does not fit on an architecture diagram. Drawing every role, policy, and attachment turns a readable picture into a permissions dump. The useful question is not how to draw IAM, it is which parts of IAM are architecture and which parts are configuration.

Try it free
6 min readFor engineers whose diagram is being buried by roles and policy attachments

See it as a diagram

Everything below, as a diagram you can edit. Describe yours and see it in seconds.

179/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

Why IAM breaks architecture diagrams

IAM objects are not topology. A role has no location, no traffic, and no failure mode a reader can trace. Worse, they multiply: a mid-sized Terraform stack routinely declares more roles, policies, and policy attachments than it declares real resources, and an attachment carries no information beyond joining two things you already drew.

The test from the include and omit rule applies cleanly here. Would a reader who never sees this role misunderstand the system? For an execution role that lets a Lambda write to its own table, no. For a role that lets a different account read your production data lake, yes, and that difference is the whole method.

Technique one: put the calling role on the edge

The architectural fact is not that a role exists, it is that a component uses it to reach another component. So write it on the arrow. An edge labelled "assumes OrderProcessorRole" or "s3:GetObject via task role" carries the identity, the direction, and the permission scope in one label, and it costs zero extra nodes.

This handles the majority of cases: execution roles, task roles, instance profiles, IRSA and Pod Identity in EKS, and service-linked roles. All of them are properties of a call that is already on the canvas.

Technique two: one identity note under the diagram

What does not fit on an edge goes into a single note block near the diagram: which compute runs under which role, which secrets each one reads, and which KMS key alias encrypts what. One block, a handful of lines, positioned so a reader finds it without leaving the canvas.

This is exactly what Datadef does when it generates from a Terraform repository, and the decision is made by resource type rather than by the model. aws_iam_role, aws_iam_policy, and aws_iam_role_policy_attachment are classified as glue in the parser catalog, which means counted and never drawn. So is any type the catalog has not seen whose name matches role, permission, grant, policy_attachment, member, iam, entitlement, or acl, which is what keeps a provider-specific identity resource nobody anticipated from becoming a box.

Nine providers are glue in their entirety: random, null, local, time, tls, archive, template, external, and terraform. That is the rule that keeps random_password.db_master and null_resource.wait_for_cluster off the canvas, and in most stacks those outnumber the databases they support. What the reader gets instead is one counted line per type beside the diagram, in the shape "14 role assignments, 8 policy attachments, 6 log groups", with the complete inventory in the generated architecture document.

## Identity notes

- checkout-svc runs as CheckoutTaskRole, reads secret /prod/checkout/db
- orders-fn runs as OrdersExecutionRole, writes to orders table, kms alias/orders
- account 333333333333 (analytics) assumes LakeReadOnlyRole here for Athena queries
- not drawn: 41 aws_iam_role_policy_attachment, 12 aws_iam_policy, 9 aws_cloudwatch_log_group
- full list: architecture.md, ## Module reference

Technique three: split when access is the subject

Some questions are genuinely about identity, and they deserve their own diagram rather than a corner of the architecture one. Federation is the clearest case: identity provider to IAM Identity Center to permission set to account, with the groups that map to each. So is a cross-account access map: which principals in which accounts can reach which resources, drawn as a bipartite picture rather than a network.

Service control policies are the third. They apply at organizational unit level and constrain everything beneath, so they belong on the organization view as annotations on the OUs, not scattered across workload diagrams.

Keeping these separate has a practical benefit beyond readability. The identity diagram has a different audience and a different review cadence, usually security rather than the workload team, and merging it into the architecture diagram means one of the two audiences is always reading past the parts that concern them.

FAQ

Should IAM roles be drawn in an AWS architecture diagram?

Only cross-account and cross-trust-boundary roles, which change how a reader understands the system. Execution roles, task roles, instance profiles, and policy attachments belong on the edge label or in an identity note, because they describe configuration rather than architecture.

How do I show that a service assumes a role?

Label the arrow between the caller and the target with the role name and the action, for example assumes OrderProcessorRole or s3:GetObject via task role. That places the identity on the call it authorises without adding a node.

When is a separate IAM diagram worth it?

When access itself is the subject: federation from an identity provider through IAM Identity Center permission sets to accounts, a cross-account access map, or a service control policy hierarchy. Those have a security audience and a different review cadence than the workload diagram.

How does an automatically generated diagram handle IAM?

By type rather than by judgement. aws_iam_role, aws_iam_policy, and aws_iam_role_policy_attachment are classified as glue in the parser catalog, so they are counted rather than drawn, and any unrecognised type whose name matches role, grant, permission, or policy_attachment falls into the same class. The counts appear as a line beside the diagram and the complete list stays in the generated architecture document.

Where do service control policies belong?

On the organization view, as annotations on the organizational units they apply to. They constrain every account beneath an OU, so attaching them to that node communicates the scope correctly, whereas repeating them in each workload diagram does not.