Datadog’s multi-account and multi-org setup isn’t about stitching together separate monitoring silos; it’s about creating a unified observability plane that scales with your complexity.
Let’s see what that looks like in practice. Imagine you’ve got a primary Datadog account (let’s call it Org-A) and you want to pull in data from a separate AWS account (AWS-B) that has its own Datadog agent and logs.
First, in Org-A’s Datadog UI, you navigate to "Integrations" -> "AWS". You’ll be prompted to create a new AWS integration. Instead of just clicking through, you’ll opt to "Add another AWS account." This is where the magic starts. Datadog will generate an IAM role ARN for you.
Now, you jump over to AWS-B. You’ll use the Datadog-provided ARN to create a new IAM role in AWS-B that trusts your Org-A Datadog account. This role needs specific permissions, typically including sts:AssumeRole and read-only access to relevant AWS services like EC2, RDS, Lambda, etc. The exact policy document is provided by Datadog during the integration setup, and it’s crucial to get this right.
Once the IAM role is set up in AWS-B, you go back to Org-A’s Datadog UI and paste the ARN of the role you just created. Datadog then uses this role to AssumeRole into AWS-B, effectively granting it read-only access to pull metrics and logs from that account.
If AWS-B also has its own Datadog agent sending data, you might not even need the IAM role for that specific data stream. You’d simply configure the agent in AWS-B to send data to your Org-A account’s API endpoint. This is done by setting the DD_API_KEY and DD_SITE environment variables for the agent. The key here is using the API key from Org-A.
The real power comes when you have multiple distinct Datadog organizations (e.g., Org-A for Dev, Org-B for Prod, Org-C for a separate business unit). You can link these using Datadog’s "Account Management" -> "Parent/Child Accounts" feature. In this scenario, Org-A becomes the parent. You then invite Org-B and Org-C as child accounts.
Once linked, dashboards, monitors, and alerts can be viewed and managed from the parent account (Org-A), aggregating data from all child accounts. You can still drill down into individual child accounts to troubleshoot specific issues. The configuration for this linking involves generating an API key in each child account and providing it to the parent account during the linking process.
The underlying mechanism for cross-account AWS integrations relies on IAM roles and the sts:AssumeRole API call. Datadog, acting as a distinct AWS principal, uses the provided role in the target account to temporarily gain permissions and query AWS APIs. For agent-based data, it’s about routing the agent’s API calls to the correct Datadog endpoint using the appropriate API key.
The most surprising thing most people miss is how granularly you can control data visibility and access between linked accounts. It’s not an all-or-nothing proposition. Within the parent account, you can define which child accounts contribute to specific dashboards or monitors, and you can set up role-based access control (RBAC) that respects these boundaries, ensuring a security engineer in Org-A can’t accidentally see sensitive production data from Org-B unless explicitly permitted.
The next step is often implementing Datadog’s CI Visibility features across these disparate environments.