Copy page

Connecting Data Sources

AWS

Monad provides comprehensive integration with Amazon Web Services (AWS) through a suite of specialized connectors. Each connector is designed to efficiently extract data from specific AWS services while maintaining security best practices and optimal performance.

Authentication Methods

AWS connectors support the following authentication methods. Choose the one that fits your deployment and security requirements:

1. IAM Role Assumption (Recommended)

How it works: Monad assumes an IAM role in your AWS account using cross-account access with an external ID for additional security.

Setup Requirements:

1. Create an IAM role in your AWS account
2. Configure the trust relationship (see template below)
3. Attach the necessary permissions for the specific service (the permissions required per connector are given in each connector's docs)
4. Provide the Role ARN to Monad

Trust Relationship Template:

Code
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AssumeRoleWithExternalId",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::339712996529:role/monad-app"
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    "sts:ExternalId": "<your-monad-org-id>"
                }
            }
        },
        {
            "Sid": "TagSession",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::339712996529:role/monad-app"
            },
            "Action": "sts:TagSession"
        }
    ]
}

Note: Replace <your-monad-org-id> with your actual Monad organization ID.

2. Static Credentials (Access Key + Secret Key)

Setup Requirements:

1. Create an IAM user with programmatic access
2. Attach the necessary permissions for the specific service (the permissions required per connector are given in each connector's docs)
3. Generate Access Key ID and Secret Access Key
4. Provide credentials to Monad securely

3. OIDC Web-Identity Federation (Kubernetes deployments outside AWS)

When to use: Monad deployments running on a Kubernetes cluster outside AWS — for example Azure AKS or Google GKE. Rather than trusting a shared Monad role or providing static keys, your AWS connectors federate directly into your AWS account using the cluster's OpenID Connect (OIDC) identity — short-lived credentials, no stored secrets, and no cross-cloud shared principal. The setup is identical regardless of which cloud hosts the cluster; only the issuer URL differs (the cluster's issuer must be publicly reachable by AWS, which every managed Kubernetes offering provides).

How it works: the connector pod presents its Kubernetes OIDC token to AWS STS (AssumeRoleWithWebIdentity) to assume a web-identity role in your account, which then assumes the target role you point the connector at:

Code
connector pod  --(OIDC web-identity)-->  web-identity role  --(AssumeRole)-->  target role  (holds the data permissions)

The Monad API makes the same calls when you press Test connection, so its service account federates into the same web-identity role.

One hand-off to Monad, then self-service. Monad needs exactly one value from you, exactly once: the ARN of the web-identity role. Monad attaches it to the Kubernetes service accounts of the Monad API and your connectors, and it never changes afterwards. Everything downstream of that role is yours to manage: adding a connector, a new AWS service, or a whole new AWS account means creating a target role that trusts your web-identity role, then pointing the connector at it. No change on Monad's side is needed, and you do not need to contact Monad.

Monad provides you:

• your cluster's OIDC issuer URL — the format is cloud-specific (e.g. Azure AKS: https://westus2.oic.prod-aks.azure.com/<tenant-id>/<cluster-id>/; GKE: https://container.googleapis.com/v1/projects/<project>/locations/<location>/clusters/<name>); use exactly what Monad provides
• the subjects to trust: system:serviceaccount:<namespace>:api (connection tests run in the API process), system:serviceaccount:<namespace>:inputs, and system:serviceaccount:<namespace>:outputs if you use AWS output connectors
• the audience: sts.amazonaws.com
• your Monad organization ID (used as the external ID on the target roles)

Setup (in your AWS account):

1. Create an IAM OIDC identity provider for the issuer URL, with sts.amazonaws.com as the audience (client ID).
2. Create a web-identity role trusted by that provider for those subjects (template below). Give it permission to assume your target roles — preferably by naming pattern, so roles you add later are covered without editing this policy.
3. Create one or more target roles that trust the web-identity role and hold the actual permissions (e.g. SQS). A target role can live in any AWS account, not only the account that holds the web-identity role. Use one target role per connector, per account, or per service — whatever matches how you manage permissions.

Web-identity role — trust policy:

Code
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "arn:aws:iam::<your-aws-account-id>:oidc-provider/<issuer-host-and-path>"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringEquals": {
                    "<issuer-host-and-path>:aud": "sts.amazonaws.com",
                    "<issuer-host-and-path>:sub": [
                        "system:serviceaccount:<namespace>:api",
                        "system:serviceaccount:<namespace>:inputs"
                    ]
                }
            }
        }
    ]
}

Web-identity role — permission to assume the target roles (recommended: by naming pattern):

Code
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AssumeMonadTargetRoles",
            "Effect": "Allow",
            "Action": "sts:AssumeRole",
            "Resource": "arn:aws:iam::*:role/monad-*"
        }
    ]
}

The * in the account position lets this role assume any role named monad-* in any AWS account. This grants nothing by itself: the assumption still succeeds only for target roles whose trust policy names this web-identity role. As long as every target role you create follows the naming convention, this policy never needs to change.

To limit assumption to accounts in your own AWS Organization, add a condition:

Code
"Condition": {
    "StringEquals": {
        "aws:ResourceOrgID": "<your-aws-organization-id>"
    }
}

If you prefer not to use a pattern, list each target role ARN explicitly in Resource instead, and add the new ARN whenever you create a target role. Either way the policy is in your account; Monad does not need to be involved.

Target role — trust policy (in whichever account the target role lives):

Code
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::<web-identity-role-account-id>:role/<web-identity-role-name>"
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    "sts:ExternalId": "<your-monad-org-id>"
                }
            }
        }
    ]
}

<web-identity-role-account-id> is the account that holds the web-identity role. When the target role is in a different account, the target role's trust policy is what authorizes the cross-account assumption; nothing else needs to be configured in the web-identity role's account.

Then:

1. Provide the web-identity role ARN to Monad — once. It is attached to the Kubernetes service accounts of the Monad API and your connectors.
2. Set each AWS connector's Role ARN to its target role ARN.

Adding a connector or a new AWS account later:

1. In the target account, create a role that follows your naming convention (e.g. monad-cloudtrail-prod), with the target-role trust policy above and the permissions the connector's docs require.
2. Set the new connector's Role ARN to that role's ARN.

That is the whole procedure; no request to Monad is needed.

Note: <issuer-host-and-path> is the issuer URL with https:// removed. Match it exactly as Monad provides it — in the OIDC provider, the Federated principal, and the :aud/:sub condition keys — including a trailing slash if the issuer has one (Azure AKS issuers end with one; GKE issuers do not). A stray or missing trailing slash causes a silent trust failure. If you use AWS output connectors, add the system:serviceaccount:<namespace>:outputs subject to the :sub array, or use StringLike with system:serviceaccount:<namespace>:*. Without the api subject, connectors still run but Test connection fails with AccessDenied.

Common Configuration Parameters

Most AWS connectors share these common configuration options:

Parameter	Type	Required	Description
Region	string	Yes	AWS region where the service is located
Role ARN	string	Conditional*	IAM role ARN for role-based authentication
Access Key	string	Conditional*	AWS Access Key ID for static credentials
Secret Key	string	Conditional*	AWS Secret Access Key for static credentials

*Required based on your chosen authentication method

Related Resources

• AWS IAM Best Practices