AWS Topology Provider

The AWS topology provider is based on the DescribeInstanceTopology API. This API returns a list of EC2 instances, where each instance record includes an array of three network IDs. These IDs describe a path through the three-tier network, from the leaf up to the root. Each network ID represents a group of physical switches that share similar characteristics and connectivity patterns. Additionally, a record might include a CapacityBlockId, which corresponds to the node’s NVLink domain.

Access to this API requires an IAM account with the AmazonEC2ReadOnlyAccess policy attached. There are two main authentication methods:

• Providing IAM credentials directly
• Assigning an IAM role to the instance running Topograph

Option 1: Using Explicit Credentials

AWS credentials consist of:

• accessKeyId
• secretAccessKey
• (Optional) token

You can provide credentials in several ways:

Credentials via File

Store your credentials in a YAML file:

1
accessKeyId: <ACCESS_KEY_ID>
2
secretAccessKey: <SECRET_ACCESS_KEY>
3
token: <OPTIONAL_TOKEN>

Then reference this file in your Topograph config:

1
http:
2
  port: 49021
3
  ssl: false
4
5
provider: aws
6
engine: slurm
7
8
credentialsPath: /path/to/credentials.yaml

Credentials via API Request Payload

Pass credentials directly in the topology request payload:

1
{
2
  "provider": {
3
    "creds": {
4
      "accessKeyId": "<ACCESS_KEY_ID>",
5
      "secretAccessKey": "<SECRET_ACCESS_KEY>",
6
      "token": "<OPTIONAL_TOKEN>"
7
    }
8
  }
9
}

Credentials via Environment Variables

Set IAM credentials as environment variables before starting the Topograph process:

1
export AWS_ACCESS_KEY_ID=<ACCESS_KEY_ID>
2
export AWS_SECRET_ACCESS_KEY=<SECRET_ACCESS_KEY>
3
export AWS_SESSION_TOKEN=<OPTIONAL_TOKEN>

Option 2: Assigning IAM Role to an Instance

Alternatively, you can assign an IAM role to the compute node running Topograph. In this case, explicit credentials are not required, as AWS automatically provides the necessary permissions. For more information, refer to the documentation.