AWS Discovery

The following sections describe the different methods of discovery that can be used with the Amazon Web Services PowerPack:

Discovering Amazon Web Services

SL1 currently supports the following methods to discover your AWS accounts:

Manual Discovery. Requires the creation of a virtual device, manual alignment of Dynamic Applications, and an IAM key. This process needs to be repeated for each AWS account.
Automated Discovery using Assume Role with single IAM key from Master Account. Provides an automated mechanism to discover all your AWS accounts within an organization using a single IAM key. This is the recommended method of discovery when your Data Collector is not an EC2 instance.
Automated Discovery when the Data Collector runs as an EC2 instance. Provides a fully automated mechanism to discover all your AWS accounts when your Data Collectors are running as EC2 instances. SL1 does not need any AWS credentials in this case. This is the recommended approach when your Data Collectors are EC2 instances.
AWS Guided Discovery. Uses guided workflows in SL1. This method is recommended when you want to use a separate IAM key for each AWS account. The guided worfklows provide a more user-friendly version of the manual process. Choose from the following workflows:

AWS EC2
AWS IAM
AWS Assume Role

NOTE: These Guided Discovery Workflows are available in SL1 version 11.2.0 and later. A basic Guided Discovery Workflow is available in earlier versions of SL1.

Before determining your method of discovery, it is recommended to define the minimum permissions policy in AWS. This policy defines the minimum permissions needed to monitor all AWS services and is needed regardless of which of the above methods is used.

You can discover a maximum of 10 accounts with the following requirements on the Data Collector:

8 cores
32 GB of RAM
100 GB of HDD

Manual Discovery

Manual discovery is used to discover a single AWS account at a time and requires an IAM key for the account.

NOTE: Using one of the Assume Role methods of discovery is recommended.

The process consists of the following steps:

Configure a user in the AWS Account
Configure the SL1 Credential
Create a Virtual Device
Align the Discovery Dynamic Application

Configuring a User in AWS

To create a read-only user account in AWS, perform the following steps:

Open a browser session and go to aws.amazon.com.

Click My Account and then select AWS Management Console. If you are not currently logged in to the AWS site, you will be prompted to log in.

In the AWS Management Console, under the Security & Identity heading, click Identity & Access Management.
After logging in, the Identity & Access Management Dashboard page appears.

To create a user account for SL1, click Users on the Dashboard menu.

Click the Create New Users button.
Enter a username for the new user, e.g. "SL1", and make sure the Generate an access key for each user checkbox is selected.

Click the Create button to generate your user account. The Create User page appears.

Click the Download Credentials button to save your Access Key ID and Secret Key as a CSV (comma-separated value) text file, and then click Close.

After creating a user, you must assign it a set of permissions policies. Click the username of the user account you created. The user's account information appears.

Under the Permissions heading, click the Attach existing policies directly button. The Add permissions page appears.

Select the checkbox for your policy based on the definition of the minimum required permissions described in the Minimum Permissions for Dynamic Applications section.
Click the Attach Policy button.

Creating the SOAP/XML Credential for AWS

To discover AWS using the manual discovery method, you must first define an AWS credential in SL1.

NOTE: If you are using an SL1 system prior to version 11.1.0, the new user interface does not include the Duplicate option for sample credential(s). ScienceLogic recommends that you use the classic user interface and the Save As button to create new credentials from sample credentials. This will prevent you from overwriting the sample credential(s).

To define an AWS credential:

Go to the Credentials page (Manage > Credentials).

Locate the AWS Credential sample credential, click its Actions icon () and select Duplicate. A copy of the credential, called AWS Credential copy appears.
Click the Actions icon () for the AWS Credential copy credential and select Edit. The Edit Credential modal page appears:

Supply values in the following fields:

Name. Type a new name for your AWS credential.
All Organizations. Toggle on (blue) to align the credential to all organizations, or toggle off (gray) and then select one or more specific organizations from the What organization manages this service? drop-down field to align the credential with those specific organizations.

Timeout (ms). Keep the default value.
URL. Enter a valid URL. This field is not used for this discovery method but must be populated with a valid URL for discovery to complete.
HTTP Auth User. Type your Access Key ID.
HTTP Auth Password. Type your Secret Access Key. The characters appear as asterisks to protect your password privacy.
Proxy Hostname/IP. Type the host name or IP address of the proxy server.

The proxy fields are required only if you are discovering AWS services through a proxy server. Otherwise, leave these fields blank.

Proxy Port. Type the port on the proxy server to which you will connect.
Proxy User. Type the username used to access the proxy server.
Proxy Password. Type the password used to access the proxy server.

If you are creating a credential from the AWS Credential - Proxy example and the proxy server does not require a username and password, then the Proxy User and Proxy Password fields must both be blank. In that scenario, if you leave the "<Proxy_User>" text in the Proxy User field, SL1 cannot properly discover your AWS services.

Embed Value [%1]. To monitor a GovCloud account, type "us-gov-west-1" or "us-gov-east-1". Otherwise, leave this field blank.

Click the Save& Close button.

Creating the SOAP/XML Credential for AWS in the SL1 Classic User Interface

To discover AWS using the manual discovery method, you must first define an AWS credential in SL1.

To define an AWS credential:

Go to the Credential Management page (System > Manage > Credentials).

Locate the AWS Credential sample credential and click its wrench icon (). The Credential Editor modal page appears.

Enter values in the following fields:

Basic Settings

Profile Name. Type a new name for your AWS credential.
URL. Enter a valid URL. This field is not used for this discovery method but must be populated with a valid URL for discovery to complete.

HTTP Auth User. Type your Access Key ID.
HTTP Auth Password. Type your Secret Access Key. The characters appear as asterisks to protect your password privacy.

Proxy Settings

The Proxy Settings fields are required only if you are discovering AWS services through a proxy server. Otherwise, leave these fields blank.

Hostname/IP. Type the host name or IP address of the proxy server.

Port. Type the port on the proxy server to which you will connect.
User. Type the username used to access the proxy server.
Password. Type the password used to access the proxy server.

If you are creating a credential from the AWS Credential - Proxy example and the proxy server does not require a username and password, then the User and Password fields must both be blank. In that scenario, if you leave the "<Proxy_User>" text in the User field, SL1 cannot properly discover your AWS services.

SOAP Options

Embed Value [%1]. To monitor a GovCloud account, type "us-gov-west-1" or "us-gov-east-1". Otherwise, leave this field blank.

Click the Save As button, and then click OK.

Creating an AWS Virtual Device for Discovery in the SL1 Classic User Interface

Because the Amazon Web Service does not have a specific IP address, you cannot discover an AWS device using discovery. Instead, you must create a virtual device that represents the Amazon Web Service. A virtual device is a user-defined container that represents a device or service that cannot be discovered by SL1. You can use the virtual device to store information gathered by policies or Dynamic Applications.

To create a virtual device that represents your Amazon service:

Go to the Device Manager page (Devices > Device Manager or Registry > Devices > Device Manager in the SL1 classic user interface).

Click the Actions button, then select Create Virtual Device. The Virtual Device modal page appears.

Enter values in the following fields:

Device Name. Enter a name for the device. For example, you could enter "Amazon Cloud" in this field.

Organization. Select the organization for this device. The organization the device is associated with limits the users that will be able to view and edit the device.
Device Class. Select Service | AWS Service.
Collector. Select the collector group that will monitor the device.

Click the Add button to create the virtual device.

Aligning the Discovery Dynamic Application

To discover your AWS account, you must manually align the "AWS: Account Discovery" Dynamic Application with the AWS virtual device. After you do so, the other Dynamic Applications in the Amazon Web Services PowerPack will automatically align to discover and monitor all of the components in your AWS account.

If your AWS account includes API Gateways or Lambda services to be monitored and you want SL1 to put those component devices in a "vanished" state if the platform cannot retrieve data about them for a specified period of time, ScienceLogic recommends setting the Component Vanish Timeout Mins. field to at least 120 minutes. For more information, see the section on Vanishing and Purging Devices.

To align the "AWS: Account Discovery" Dynamic Application to your virtual device:

Go to the Devices page.

Click the AWS virtual device and click on it to open the Device Investigator.
In the Device Investigator, click the Collections tab. The Dynamic Application Collections page appears.
Click the Edit button and then click the Align Dynamic App button.
In the Align Dynamic Application page, click Choose Dynamic Application.
In the Choose Dynamic Application page, locate the credential you created for your AWS service and select it.

Click the Select button and then click the Align Dynamic App button.

Aligning the Discovery Dynamic Application in the SL1 Classic User Interface

To align the "AWS: Account Discovery" Dynamic Application to your virtual device:

Go to the Device Manager page (Registry > Devices > Device Manager).

Click the wrench icon () for your virtual device.
In the Device Administration panel, click the Collections tab. The Dynamic Application Collections page appears.
Click the Actions button, and then select Add Dynamic Application from the menu.
In the Dynamic Application Alignment modal page, select AWS: Account Discovery in the Dynamic Applications field.
In the Credentials field, select the credential you created for your AWS service.

Click the Save button to align the Dynamic Application.

Automated Discovery Using AssumeRole with a Single IAM Key from the AWS Master Account

Automated discovery using AssumeRole with an IAM key is the recommended approach to monitor your AWS accounts when your Data Collectors are not acting as EC2 instances. In this method of discovery, your organization will be discovered first and then the accounts within the organization will be created automatically.

This method of discovery has the following benefits:

Only a single IAM key needs to be managed on SL1, instead of an IAM key for every AWS account.
The IAM key is only used to get the information about the organization, and all the actual monitoring is done via temporary tokens, which is the recommended approach by AWS.

This method can also be used in the following scenarios:

When a proxy server is between the Data Collector and the AWS cloud
When Ping is not available
In the Government cloud

NOTE: All examples shown are for commercial AWS accounts. When AWS Gov is being monitored, the JSON data that refers to ARN will need to be modified from "aws" to "aws-us-gov". For example: Resource": "arn:aws:iam::<account number>:role/Sciencelogic-Monitor would need to be Resource: arn:aws-us-gov:iam::<account number>:role/Sciencelogic-Monitor

To use this method of discovery, perform the following steps:

Configure a user in the master billing account
Create a role in each account
Configuring the SL1 credential
Create and run the discovery session

NOTE: If Ping is blocked, then you must follow the steps in the Manually Create the Organization and Align the Dynamic Applications section.

Configure a User in the Master Billing Account

The first step in this discovery method is to create a policy that defines the permissions needed by SL1. To do this, copy the policy below into an editor:

{
   "Version": "2012-10-17",
   "Statement": [
      {
         "Sid": "VisualEditor0",
         "Effect": "Allow",
         "Action": [
            "organizations:ListAccounts",
            "organizations:DescribeOrganization",
            "organizations:DescribeAccount"
         ],
         "Resource": "*"
      },
      {
         "Sid": "VisualEditor1",
         "Effect": "Allow",
         "Action": "sts:AssumeRole",
         "Resource": "arn:aws:iam::<account number>:role/Sciencelogic-Monitor"
      }
   ]
}

For each account that needs to be monitored, duplicate the "Resource": "arn:aws:iam::<Account Number>:role/Sciencelogic-Monitor" line and set the <Account Number> to the correct account number.

After editing the policy, perform the following steps in the AWS console:

Go to IAM > Policies > Create Policy. Select the JSON tab and copy the edited JSON text into the AWS console.
Click Next: Tags and then click Next: Review.
Type a name for the policy (for example, "SL1MasterBillingPermissions") and then select Create Policy.
To create a user in the master billing account, go to IAM > Users > Add User.
Type the user's name and select the option for Programmatic Access. Click Next: Permissions.
Select Attach existing policies directly and select the checkbox for the policy you created.
Select Next: Tags > Next: Review > Create User.

NOTE: The Access Key and Secret Key need to be saved as these will be needed when configuring the SL1 credential.

Create a Role in Each Account

In every AWS account that is to be monitored, a role with the same name needs to be created. The default name is "ScienceLogic-Monitor". To create the role, perform the following steps for each account that is to be monitored:

In the AWS console, go to IAM > Roles and select Create Role.
Select Another AWS Account and enter the account ID of the Master Billing Account. Select Next: Permissions.
Select the policy that was created in the Minimum Permissions Needed to Monitor Your AWS Accounts section.
Select Next: Tags and then Next: Review.
Enter "ScienceLogic-Monitor" in the Role name field and then select Create role.
Repeat these steps for each AWS account that you want to monitor.

Next you will need to edit the trust relationship of the role to restrict the principle to the user you created. To do this:

In the AWS console, go to IAM > Roles and select the "ScienceLogic-Monitor" role.
Select the Trust Relationships tab and click Edit trust relationship.
Edit the JSON to look like the following:

            {
   "Version": "2012-10-17",
   "Statement": [
      {
         "Effect": "Allow",
         "Principal": [
            "AWS": "arn:aws:iam::<Master Billing Account>:user/<Master Billing Account User>"
      },

      {
         "Action": "sts:AssumeRole",
         "Condition": {}
      }
   ]
}

NOTE: The ARN above is the ARN of the user that was created in the previous steps.

Once you have updated the policy, click Update Trust Policy.

Configure the SL1 Credential

You can use your master organization account to automatically discover all AWS accounts, instead of having to enter a key for each account. This process will also create a separate DCM tree for each account.

NOTE: Ensure that you use the "AWS Credential - Master Account" credential, as this credential is valid for AssumeRole and has the correct headers for AssumeRole discovery. Do not use the classic "AWS Credential" to discover an AssumeRole pingable device, as it will not work.

NOTE: Discovery of China accounts does not support alignment using AssumeRole. For those accounts customers must continue to use manual alignment of Dynamic Applications.

To define the credential:

Go to the Credentials page (Manage > Credentials.

Locate the AWS Credential - Master Account sample credential, click its Actions icon () and select Duplicate. A copy of the credential, called AWS Credential - Master Account copy appears.
Click the Actions icon () for the AWS Credential - Master Account copy credential and select Edit. The Edit Credential modal page appears:

Enter values in the following fields:

Name. Type a new name for your AWS credential.
All Organizations. Toggle on (blue) to align the credential to all organizations, or toggle off (gray) and then select one or more specific organizations from the What organization manages this service? drop-down field to align the credential with those specific organizations.
URL. Type https://organizations.us-east-1.amazonaws.com in the field. If your administrator has configured a different region, you can change it or use the default region. To discover Gov accounts using AssumeRole, type https://organizations.us-gov-west-1.amazonaws.com

HTTP Auth User. Type the AWS access key ID of the user you created in the master account.
HTTP Auth Password. Type the AWS secret access key of the user created in the master account.

Under HTTP Headers, you can edit the following options:

AssumeRole. Type the AWS Role you created in each account. The default name is "ScienceLogic-Monitor".
AssumeRoleSession. Optional. The default value is "AssumeRoleSession:SL1".
Regions. The regions entered in this field will be discovered. For example, entering "Regions:ap-southeast-2, us-east-2" will discover two regions. If left blank, all regions will be discovered. To restrict discovery of a region, type a "!" in front of the region, for example, Regions: !us-east-1. The default value is "Regions:ALL".
OrganizationCreation:NAME:ID. Autocreates an SL1 organization for accounts using AssumeRole. You can enter one of the following options:

OrganizationCreation:NAME. The name of the organization will contain the name of the user.
OrganizationCreation:ID. The name of the organization will contain the ID of the user.
OrganizationCreation:ID:NAME. The name of the organization will contain both the ID and name of the user, in that order.
OrganizationCreation:NAME:ID. The name of the organization will contain both the name and ID of the user, in that order.

NOTE: The existing organization will be changed by this setting only if it is the default (System) organization. If this header is not included, then all the discovered accounts will be placed into the organization selected in the discovery session.

Click the Save & Close button.

NOTE: If the "AWS: Account Creation" Dynamic Application is reporting that it is unable to use your AssumeRole, double-check your trust relationships on your configured roles.

Configure the SL1 Credential in the SL1 Classic User Interface

NOTE: Discovery of China accounts does not support alignment using AssumeRole. For those accounts customers must continue to use manual alignment of Dynamic Applications.

To define the credential:

Go to the Credential Management page (System > Manage > Credentials).

Locate the AWS Credential - Master Account sample credential that you need and click its wrench icon (). The Credential Editor modal page appears.

Enter values in the following fields:

Basic Settings

Profile Name. Type a new name for your AWS credential.
URL. Type https://organizations.us-east-1.amazonaws.com in the field. If your administrator has configured a different region, you can change it or use the default region. To discover Gov accounts using AssumeRole, type https://organizations.us-gov-west-1.amazonaws.com

HTTP Auth User. Type the AWS access key ID of the user you created in the master account.
HTTP Auth Password. Type the AWS secret access key of the user created in the master account.

HTTP Headers

Click + Add a header to add a header field. You can enter the following options:

AssumeRole. Type the AWS Role you created in each account. The default name is "ScienceLogic-Monitor".
AssumeRoleSession. Optional. The default value is "AssumeRoleSession:SL1".
Regions. The regions entered in this field will be discovered. For example, entering "Regions:ap-southeast-2, us-east-2" will discover two regions. If left blank, all regions will be discovered. To restrict discovery of a region, type a "!" in front of the region, for example, Regions: !us-east-1. The default value is "Regions:ALL".
OrganizationCreation:NAME:ID. Autocreates an SL1 organization for accounts using AssumeRole. You can enter one of the following options:

OrganizationCreation:NAME. The name of the organization will contain the name of the user.
OrganizationCreation:ID. The name of the organization will contain the ID of the user.
OrganizationCreation:ID:NAME. The name of the organization will contain both the ID and name of the user, in that order.
OrganizationCreation:NAME:ID. The name of the organization will contain both the name and ID of the user, in that order.

Click the Save As button, and then click OK.

NOTE: If the "AWS: Account Creation" Dynamic Application is reporting that it is unable to use your AssumeRole, double-check your trust relationships on your configured roles.

Create and Run the Discovery Session

To discover AWS Accounts in an AWS Organization using AssumeRole, perform the following steps:

NOTE: If Ping is not supported between the Data Collector and AWS, you can skip this section and go to the Manually Create the Organization and Align Dynamic Applications section.

On the Devices page () or the Discovery Sessions page (Devices > Discovery Sessions), click the Add Devices button. The Select page appears:

Click the Unguided Network Discovery button. Additional information about the requirements for discovery appears in the General Information pane to the right.
Click Select. The Basic Information page appears.

Supply values in the following fields:

Name. Type a unique name for this discovery session. This name is displayed in the list of discovery sessions on the Discovery Sessions tab.
Description. Optional. Type a short description of the discovery session. You can use the text in this description to search for the discovery session on the Discovery Sessions tab.
Select the organization to add discovered devices to. Select the name of the organization to which you want to add the discovered devices.

Click Next. The Credential Selection page of the Add Devices wizard appears:

On the Credential Selection page, locate and select the credential you created.
Next. The Discovery Session Details page of the Add Devices wizard appears:

Complete the following fields:

List of IPs/Hostnames. Type the URL of your AWS master billing account.
Which collector will monitor these devices?. Required. Select an existing collector to monitor the discovered devices.
Run after save. Select this option to run this discovery session as soon as you save the session.

In the Advanced options section, click the down arrow icon () to complete the following fields:

Discover Non-SNMP. Enable this setting.
Model Devices. Enable this setting.

Click Save and Run if you enabled the Run after save setting, or Save and Close to save the discovery session. The Discovery Sessions page (Devices > Discovery Sessions) displays the new discovery session.
If you selected the Run after save option on this page, the discovery session runs, and the Discovery Logs page displays any relevant log messages. If the discovery session locates and adds any devices, the Discovery Logs page includes a link to the Device Investigator page for the discovered device.

NOTE: If you discontinue monitoring on any devices that are using the Assume Role authentication method, ScienceLogic recommends the best practice of first disabling the devices, deleting the devices from the DCM tree, and then cleaning up any AWS permissions in IAM. This will avoid any unnecessary alerts.

Create and Run the Discovery Session in the SL1 Classic User Interface

To discover AWS Accounts in an AWS Organization using AssumeRole, perform the following steps:

NOTE: If Ping is not supported between the Data Collector and AWS, you can skip this section and go to the Manually Create the Organization and Align Dynamic Applications section.

Go to the Discovery Control Panel page (System > Manage > Classic Discovery).

Click the Create button. The Discovery Session Editor page appears.

Supply values in the following fields:

IP Address Discovery List. Type the URL of you previously used in the credential creation step.

Other Credentials. Select the credential you created.
Discover Non-SNMP. Select this checkbox.
Model Devices. Select this checkbox.

Optionally, supply values in the other fields in this page. For a description of the fields in this page, see the Discovery and Credentials section.
Click the Save button.
The Discovery Control Panel page will refresh. Click the lightning bolt icon () for the discovery session you just created.
In the pop-up window that appears, click the OK button. The page displays the progress of the discovery session.

Manually Creating the Organization and Aligning Dynamic Applications

NOTE: The following steps are needed only if ping is not supported between the Data Collector and AWS.

To create a virtual device to create the organization:

Go to the Device Manager page (Devices > Device Manager or Registry > Devices > Device Manager in the SL1 classic user interface).

Click the Actions button, then select Create Virtual Device. The Virtual Device modal page appears:

Enter values in the following fields:

Device Name. Enter a name for the device. For example, you could enter "Amazon Organization" in this field.

Organization. Select the organization for this device. The organization the device is associated with limits the users that will be able to view and edit the device.
Device Class. Select AWS| Organization.
Collector. Select the collector group that will monitor the device.

Click the Add button to create the virtual device.

Next, you must manually align the "AWS: Account Creation" Dynamic Application with the AWS virtual device. After you do so, the other Dynamic Applications in the Amazon Web Services PowerPack will automatically align to discover and monitor all of the components in your AWS account.

To align the "AWS: Account Creation" Dynamic Application to your virtual device:

Go to the Devices page.

Locate your virtual device and click its name to open the Device Investigator.
In the Device Investigator page, click the Collections tab. The Dynamic Application Collections page appears.
Click the Edit button and then click the Align Dynamic App button.
In the Align Dynamic Application page, click Choose Dynamic Application.
In the Choose Dynamic Application page, select AWS: Account Creation.
In the Align Dynamic Application page, click Choose Credential.
In the Choose Credential page, select the credential you created and then click the Select button.
Click the Align Dynamic App button to align the Dynamic Application.

Automated Discovery when the Data Collector Runs as an EC2 Instance

This method of discovery is recommended for monitoring your AWS accounts within an organization when your Data Collectors are EC2 instances. In this case, a standard SL1 discovery process is created, and this mechanism will first discover your organization and then create all the accounts within the organization.

This method of discovery has the following benefits:

No AWS credentials are needed in SL1

NOTE: All examples shown are for commercial AWS accounts. When AWS Gov is being monitored, the JSON data that refers to ARN will need to be modified from "aws" to "aws-us-gov". For example: Resource": "arn:aws:iam::<account number>:role/Sciencelogic-Monitor would need to be Resource": "arn:aws:iam-us-gov::<account number>:role/Sciencelogic-Monitor

To use this method of discovery, perform the following steps:

Create an AWS role in the master billing account
Create an AWS role in account that the collector is in
Create an AWS role in each account that is to be monitored
Create an SL1 credential
Create and run the discovery session

Create a Role in the Master Billing Account

The role you will create in the master billing account is assumed from the account that the EC2 instance is in. This role will enable SL1 to temporarily log in to the master billing account and discover other accounts.

Before creating the role, you must first create a policy that defines the permissions needed by SL1. To do this, copy the policy from below into an editor:


{ "Version": "2012-10-17",
   "Statement": 
      {"Sid": "VisualEditor0",
	  "Effect": "Allow",
	  "Action": [
	     "organizations:ListAccounts",
	     "organizations:DescribeOrganization",
            "organizations:DescribeAccount"
	   ],
	   "Resource": "*"
      }
}

Next, perform the following steps:

Log in to the Master Billing Account via the AWS console and select IAM > Policies > Create Policy.
Select the JSON tab and paste the JSON text you copied above into the AWS console.
Click Next: Tags and then click Next: Review.
Type a name for the policy (for example, "SL1MasterBillingPermissions") in the Name field and then click Create Policy.

To create the role:

Go to IAM > Roles > Create Role.
Under Select type of trusted entity, select Another AWS account.
Type the account number of the account that contains the EC2 instance running on the collector in the Account ID field, and then click Next: Permissions.
Select the checkbox for the policy you created above.
Click Next: Tags and then click Next: Review.
Type the role name from the example above (SL1MasterAccountRole) in the Role name field, then click Create role.

The trust policy is set up by the console automatically as follows:


{    
   "Version": "2012-10-17",
   "Statement": [
      {
	  "Effect": "Allow",
	  "Principal": {
	   "AWS": "arn:aws:iam::581618222958:root"
	  },
	  "Action": "sts:AssumeRole",
	  "Condition":{}

        }
      ]
    }

In the console, edit the trust relationship and replace :root with :role/ec2-collector.

NOTE: "ec2-collector" is the name of the role that will be created in the account that the EC2 collector is in. This policy allows only the "ec2-colletor" role to assume this role in the master billing account. If you use another name for the role, then this trust relationship must use that name instead of "ec2-collector".

Create an AWS Role in the Account your Data Collector is In

The role you create in the account your Data Collector is in will be assigned to the EC2 instances that house those Data Collectors. This role enables the SL1 Data Collector to assume a role in the master billing account, which is then used to discover the organization and retrieve the accounts associated with that organization. Once the accounts have been discovered, this role allows SL1 to assume the monitor role in each of the accounts.

First you will need to create a policy in the accounts that the Data Collectors are in. To create this policy, first cut and paste the following JSON text into an editor:

            {
   "Version": "2012-10-17",
   "Statement": [
      {
         "Sid": "VisualEditor0",
         "Effect": "Allow",
         "Action": "sts:AssumeRole",
         "Resource": [
		     "arn:aws:iam::<master billing account ID>:role/SL1MasterAccountRole",
		     "arn:aws:iam::<monitored account 1>:role/ScienceLogic-Monitor",
		     "arn:aws:iam::<monitored account 2>:role/ScienceLogic-Monitor",
	             "arn:aws:iam::<monitored account 3>:role/ScienceLogic-Monitor"
	  ]
      }
   ]
}

Replace the "master billing account" with your master billing account number.

For each account to be monitored, ensure that there is a line under Resource that matches the account ID. The example above shows three accounts to be monitored.

NOTE: If the master billing account is to be monitored, it will also need a line in the Resource list.

If you did not use the example "SL1MasterAccountRole" name, replace it with the name of your role.

Next, perform the following steps:

Log in to the AWS console and select IAM > Policies > Create Policy.
Select the JSON tab and copy the JSON text you edited above into the AWS console.
Click Next: Tags and then click Next: Review.
Type a name for the policy (for example, "EC2CollectorPolicy") in the Name field and then click Create Policy.

To create the role:

NOTE: If you already have a role assigned to the Data Collector that houses the EC2 instance, then you can add the policy you just created to that existing role. Otherwise, follow the steps below to create the role.

Go to IAM > Roles > Create Role.
Under Select type of trusted entity, select AWS service.
Under Choose a use case, select EC2.
Click Next: Permissions and select the policy you created above.
Click Next: Tags and then click Next: Review.
Type the name from our example (ec2-collector) in the Role name field, then click Create role.

Next, you need to assign this instance profile to the EC2 instances that are Data Collectors. To do this:

Go to the AWS console and click EC2 > Instances.
Select the checkbox for each instance that is a Data Collector.
Click Actions > Security > Modify IAM Role.
In the drop-down field, select the role that you just created and then click Save.

Create a Role in Each Account

In every account that is to be monitored, a role with the same name needs to be created. The default name is ScienceLogic-Monitor. The following steps must be performed for each account that is to be monitored:

In the AWS console for the account and go to IAM > Roles > Create Role.
Under Select type of trusted entity, select Another AWS account.
Type the account number that houses the EC2 collectors in the Account ID field, and then click Next: Permissions.
Select the checkbox for the policy you created in the Minimum Permissions Needed to Monitor Your AWS Accounts section (called "SL1MinimumPermissions").
Click Next: Tags and then click Next: Review.
Type ScienceLogic-Monitor in the Role name field, then click Create role.
Click on the role that was just created and select the Trust Relationships tab.
Click the Edit trust relationship button.
In the Policy Document editor, change the Principle from "AWS": "arn:aws:iam::<ec2 collector account>:root to "AWS": "arn:aws:iam::<collector account>:role/ec2-collector" (where ec2-collector is the name of the role created on the account housing the EC2 collector). Then click the Update Trust Policy button.
Repeat these steps for each account that is to be monitored.

Configuring the Credential to Discover AWS on an EC2 Collector

To define an AWS credential to discover AWS on an EC2 collector:

Go to the Credentials page (Manage > Credentials.

Locate the AWS Credential - EC2 Instance sample credential, click its Actions icon () and select Duplicate. A copy of the credential, called AWS Credential - Master Account copy appears.
Click the Actions icon () for the AWS Credential - EC2 Instance copy credential and select Edit. The Edit Credential modal page appears:

Enter values in the following fields:

Name. Type a new name for your AWS credential.
All Organizations. Toggle on (blue) to align the credential to all organizations, or toggle off (gray) and then select one or more specific organizations from the What organization manages this service? drop-down field to align the credential with those specific organizations.
URL. Type https://organizations.us-east-1.amazonaws.com in the field. If your administrator has configured a different region, you can change it or use the default region. To discover Gov accounts using AssumeRole, type https://organizations.us-gov-west-1.amazonaws.com.

HTTP Auth User. Leave the default value "IAM" in the field.
HTTP Auth Password. Leave the default value.

Under HTTP Headers, edit the following options:

OrganizationArn. Defines the ARN for the AssumeRole. This is the ARN of the role created in the master billing account. In the example above it was called "SL1MasterAccountRole". For example, OrganizationArn:arn:aws:iam::<Master Billing Account>:role/SL1MasterAccountRole
AssumeRole. Type the AWS Role you created in each account. The default name is "ScienceLogic-Monitor".
AssumeRoleSession. Optional. The default value is "AssumeRoleSession:SL1".
Regions. The regions entered in this field will be discovered. For example, entering "Regions:ap-southeast-2, us-east-2" will discover two regions. If left blank, all regions will be discovered. To restrict discovery of a region, type a "!" in front of the region, for example, Regions: !us-east-1. The default value is "Regions:ALL".
OrganizationCreation:NAME:ID. Autocreates an SL1 organization for accounts using AssumeRole. You can enter one of the following options:

OrganizationCreation:NAME. The name of the organization will contain the name of the user.
OrganizationCreation:ID. The name of the organization will contain the ID of the user.
OrganizationCreation:ID:NAME. The name of the organization will contain both the ID and name of the user, in that order.
OrganizationCreation:NAME:ID. The name of the organization will contain both the name and ID of the user, in that order.

Click the Save & Close button.

Configuring the Credential to Discover AWS on an EC2 Collector in the SL1 Classic User Interface

To define an AWS credential to discover AWS on an EC2 collector:

Go to the Credential Management page (System > Manage > Credentials).

Locate the AWS Credential - EC2 Instance sample credential that you need and click its wrench icon (). The Credential Editor modal page appears.

Enter values in the following fields:

Basic Settings

Profile Name. Type a new name for your AWS credential.
URL. Type https://organizations.us-east-1.amazonaws.com in the field. If your administrator has configured a different region, you can change it or use the default region. To discover Gov accounts using AssumeRole, type https://organizations.us-gov-west-1.amazonaws.com.
HTTP Auth User. Leave the default value "IAM" in the field.

SOAP Options

Embed Value [%2]:

If you are using the AWS Config service and want to discover only regions that have that service enabled, type "[AUTO]" in this field. After discovery, only regions that have AWS Config enabled will be displayed in the dynamic component map tree. Global resources will also be discovered.
If you are using not using the AWS Config service, type "[FILTER]" in this field so it will discover only regions that are reporting CloudWatch metrics. This will reduce the number of regions being monitored and the load on the Data Collector.

HTTP Headers

Click + Add a header to add a header field. You can enter the following options:

OrganizationArn. Defines the ARN for the AssumeRole. This is the ARN of the role created in the master billing account. In the example above it was called "SL1MasterAccountRole". For example, OrganizationArn:arn:aws:iam::<Master Billing Account>:role/SL1MasterAccountRole
AssumeRole. Type the AWS Role you created in each account. The default name is "ScienceLogic-Monitor".
AssumeRoleSession. Optional. The default value is "AssumeRoleSession:SL1".
Regions. The regions entered in this field will be discovered. For example, entering "Regions:ap-southeast-2, us-east-2" will discover two regions. If left blank, all regions will be discovered. To restrict discovery of a region, type a "!" in front of the region, for example, Regions: !us-east-1. The default value is "Regions:ALL".
OrganizationCreation:NAME:ID. Autocreates an SL1 organization for accounts using AssumeRole. You can enter one of the following options:

OrganizationCreation:NAME. The name of the organization will contain the name of the user.
OrganizationCreation:ID. The name of the organization will contain the ID of the user.
OrganizationCreation:ID:NAME. The name of the organization will contain both the ID and name of the user, in that order.
OrganizationCreation:NAME:ID. The name of the organization will contain both the name and ID of the user, in that order.

NOTE: The existing organization will be changed by this setting only if it is the default (System) organization.

Click the Save As button, then click OK.

Create and Run the Discovery Session

To discover AWS Accounts in an AWS Organization using AssumeRole, perform the following steps:

NOTE: If you are upgrading the PowerPack and had previously discovered accounts within an organization separately and now want to use a different discovery method, you must first disable the "AWS: Account Discovery" Dynamic Application in each account that is being upgraded.

On the Devices page () or the Discovery Sessions page (Devices > Discovery Sessions), click the Add Devices button. The Select page appears:

Click the Unguided Network Discovery button. Additional information about the requirements for discovery appears in the General Information pane to the right.
Click Select. The Basic Information page appears.

Supply values in the following fields:

Name. Type a unique name for this discovery session. This name is displayed in the list of discovery sessions on the Discovery Sessions tab.
Description. Optional. Type a short description of the discovery session. You can use the text in this description to search for the discovery session on the Discovery Sessions tab.
Select the organization to add discovered devices to. Select the name of the organization to which you want to add the discovered devices.

Click Next. The Credential Selection page of the Add Devices wizard appears:

On the Credential Selection page, locate and select the credential you created.
Next. The Discovery Session Details page of the Add Devices wizard appears:

Complete the following fields:

List of IPs/Hostnames. Type the URL of your AWS master billing account.
Which collector will monitor these devices?. Required. Select an existing Data Collector to monitor the discovered devices.
Run after save. Select this option to run this discovery session as soon as you save the session.

In the Advanced options section, click the down arrow icon () to complete the following fields:

Discover Non-SNMP. Enable this setting.
Model Devices. Enable this setting.

Click Save and Run if you enabled the Run after save setting, or Save and Close to save the discovery session. The Discovery Sessions page (Devices > Discovery Sessions) displays the new discovery session.
If you selected the Run after save option on this page, the discovery session runs, and the Discovery Logs page displays any relevant log messages. If the discovery session locates and adds any devices, the Discovery Logs page includes a link to the Device Investigator page for the discovered device.

Create and Run the Discovery Session in the SL1 Classic User Interface

To discover AWS Accounts in an AWS Organization using AssumeRole, perform the following steps:

Go to the Discovery Control Panel page (System > Manage > Classic Discovery).

Click the Create button. The Discovery Session Editor page appears.

Supply values in the following fields:

IP Address Discovery List. Type the URL of your AWS master billing account.

Other Credentials. Select the credential you created.
Discover Non-SNMP. Select this checkbox.
Model Devices. Select this checkbox.

Optionally, supply values in the other fields in this page. For a description of the fields in this page, see the Discovery and Credentials section.
Click the Save button.
The Discovery Control Panel page will refresh. Click the lightning bolt icon () for the discovery session you just created.
In the pop-up window that appears, click the OK button. The page displays the progress of the discovery session.

AWS Guided Discovery

You can use the Universal Discovery Framework process in SL1 that guides you through a variety of existing discovery types in addition to traditional SNMP discovery. This process, which is also called "guided discovery", lets you pick a discovery type based on the type of devices you want to monitor. The Universal Discovery workflow includes a button for Amazon Web Services.

If you want to discover one of the third-party products that are available as an option when using the Universal Discovery workflow, you must have the corresponding PowerPack installed on your SL1 system to ensure that the appropriate Dynamic Applications, Device Classes, and other elements can be utilized for discovery. For example, if you want to discover an Amazon Web Services account, you must have the Amazon Web Services PowerPack installed.

If you use guided discovery and need to upgrade to a new version of the Amazon Web Services PowerPack, do not uninstall the PowerPack on SL1 versions 11.2.0 and above first, as guided discovery workflows will be lost. Follow the upgrade instructions in the Amazon Web Services PowerPack release notes.

To run a guided or Universal Discovery:

On the Devices page () or the Discovery Sessions page (Devices > Discovery Sessions), click the Add Devices button. The Select page appears.

Select the Amazon Web Services button. Additional information about the requirements for device discovery appears in the General Information pane to the right. If you are on SL1 11.2.0 or later, you will be prompted to select a type of AWS guided discovery from the following:

AWS EC2
AWS IAM
AWS Assume Role

When executing AWS guided discoveries, executing the same type of guided discovery with similar settings can result in asset duplication. For IAM guided discoveries, this will result in duplicated account device component trees. For other AWS guided discovery types, this might result in duplicated virtual devices that represent the AWS organization.

Click Select. The Credential Selection page appears:

During the guided discovery process, you cannot click Next until the required fields are filled on the page, nor can you skip to future steps. However, you can revisit previous steps that you have already completed.

On the Credential Selection page of the guided discovery process, will select the AWS credential for the guided workflow that you chose. If you are not yet on SL1 version 11.2.0, select the credential that you configured for basic guided discovery. If you have not yet configured a credential, go to the Credentials page (Manage > Credentials) and configure the type of credential you will need:

AWS Assume Role Credential
AWS EC2 Credential
AWS IAM Credential

Defining an AWS Assume Role Credential

SL1 includes an AWS Assume Role credential type that you can use to connect with the AWS service during guided discovery using the Assume Role discovery method. The Assume Role discovery method provides an automated mechanism to discover all your AWS accounts within an organization using a single IAM key. This credential type uses field names and terminology that are specific to the AWS service.

For more information about monitoring AWS using Assume Role, see the section on Automated Discovery Using Assume Role with a Single IAM Key from the AWS Master Account.

To define an AWS Assume Role credential:

Go to the Credentials page (Manage > Credentials).
Click the Create New button and then select Create AWS Assume Role Credential. The Create Credential modal page appears:

Supply values in the following fields:

Name. Type a unique name for the credential. Can be any combination of alphanumeric characters, up to 64 characters.
All Organizations. Toggle on (blue) to align the credential to all organizations, or toggle off (gray) and then select one or more specific organizations from the Select the organizations the credential belongs to drop-down field to align the credential with those specific organizations.

To learn more about credentials and organizations, see the section Aligning Organizations With a Credential.

Timeout (ms). Type the time, in milliseconds, after which SL1 will stop trying to communicate with the device from which you want to retrieve data.
AWS Access Key ID. Type the Access Key ID for an account on the AWS device to be monitored.
AWS Secret Access Key. Type the Secret Access Key for an account on the AWS device to be monitored.
Cloud Type. Select the AWS cloud type that will be accessed with the credential. This field is required. Choices are:

Standard. Select this option if you want to connect to a standard AWS account.
GovCloud. Select this option if you want to connect to an AWS GovCloud account.

Assume Role. Type the AWS Role you created in each account. The default name is "ScienceLogic-Monitor".
Assume Role Session. Optional. The default value is "SL1".
Organization Creation. Auto-creates an SL1 organization for accounts using AssumeRole. You can type one of the following options:

Credentials created for guided discovery workflows do not need "OrganizationCreation" typed before the Name and/or ID.

NAME. The name of the organization will contain the name of the user.
ID. The name of the organization will contain the ID of the user.
ID:NAME. The name of the organization will contain both the ID and name of the user, in that order.
NAME:ID. The name of the organization will contain both the name and ID of the user, in that order.

Configuration. Ignore this setting when using guided discovery as the PowerPack will automatically determine which regions will be utilized.

Regions. Type the AWS regions that you want to discover. For example, entering "ap-southeast-2, us-east-2" will discover two regions. If left blank, all regions will be discovered. To restrict discovery of a region, type a "!" in front of the region, for example, Regions: !us-east-1. The default value is "ALL".
Filter by Tags. To discover AWS devices and filter them by tags, type the tag operation, tag key, and tag value, in the following format: <operation>#<tag name>#<tag value>. For example, if you want to filter by Tag Name, you would type the following:

Tags:equals#Name#Example

Valid operations include:

equals
notEquals
contains
notContains

You can chain together multiple filters separating them by a comma. For example:

Tags:equals#Name#Example,contains#Owner#Someone

Proxy Hostname/IP. Type the host name or IP address of the proxy server.
Proxy Port. Type the port number on the proxy server to which you will connect.
Proxy User. Type the username to use to access the proxy server.
Proxy Password. Type the password to use to access the proxy server.

If you use a proxy server in front of the AWS devices you want to communicate with, enter values in the proxy fields. Otherwise, you can skip these fields.

Click Save & Close.

If you would like to test your credential using the Credential Tester panel, click Save & Test. For detailed instructions on using the Credential Tester panel, see the Testing the AWS Credential section.

Defining an AWS EC2 Credential

SL1 includes an AWS EC2 credential type that you can use to connect with the AWS service during guided discovery when your Data Collectors are EC2 instances. This credential type uses field names and terminology that are specific to the AWS service.

For more information about monitoring AWS accounts within an organization when your Data Collectors are EC2 instances, see the section on Automated Discovery when the Data Collector Runs as an EC2 Instance.

To define an EC2 credential:

Go to the Credentials page (Manage > Credentials).
Click the Create New button and then select Create AWS EC2 Credential. The Create Credential modal page appears:

Supply values in the following fields:

Name. Type a unique name for the credential. Can be any combination of alphanumeric characters, up to 64 characters.
All Organizations. Toggle on (blue) to align the credential to all organizations, or toggle off (gray) and then select one or more specific organizations from the Select the organizations the credential belongs to drop-down field to align the credential with those specific organizations.

To learn more about credentials and organizations, see the section Aligning Organizations With a Credential.

Timeout (ms). Type the time, in milliseconds, after which SL1 will stop trying to communicate with the device from which you want to retrieve data.
Cloud Type. Select the AWS cloud type that will be accessed with the credential. This field is required. Choices are:

Standard. Select this option if you want to connect to a standard AWS account.
GovCloud. Select this option if you want to connect to an AWS GovCloud account.

NOTE: To use a Government account, the EC2 or All-in-One Data Collector should be created on one GovCloud child account.

Organization Arn. Type the Amazon Resource Name (ARN) for the Assume Role. This is the ARN of the role created in the master billing account.
Assume Role. Type the AWS Role you created in each account. The default name is "ScienceLogic-Monitor".
Assume Role Session. Optional. The default value is "SL1".
Organization Creation. Auto-creates an SL1 organization for accounts using AssumeRole. You can type one of the following options:

Credentials created for guided discovery workflows do not need "OrganizationCreation" typed before the Name and/or ID.

NAME. The name of the organization will contain the name of the user.
ID. The name of the organization will contain the ID of the user.
ID:NAME. The name of the organization will contain both the ID and name of the user, in that order.
NAME:ID. The name of the organization will contain both the name and ID of the user, in that order.

Configuration. Ignore this setting when using guided discovery as the PowerPack will automatically determine which regions will be utilized.

Regions. Type the AWS regions that you want to discover. For example, entering "ap-southeast-2, us-east-2" will discover two regions. If left blank, all regions will be discovered. To restrict discovery of a region, type a "!" in front of the region, for example, Regions: !us-east-1. The default value is "ALL".
Filter by Tags. To discover AWS devices and filter them by tags, type the tag operation, tag key, and tag value, in the following format: <operation>#<tag name>#<tag value>. For example, if you want to filter by Tag Name, you would type the following:

Tags:equals#Name#Example

Valid operations include:

equals
notEquals
contains
notContains

You can chain together multiple filters separating them by a comma. For example:

Tags:equals#Name#Example,contains#Owner#Someone

Proxy Hostname/IP. Type the host name or IP address of the proxy server.
Proxy Port. Type the port number on the proxy server to which you will connect.
Proxy User. Type the username to use to access the proxy server.
Proxy Password. Type the password to use to access the proxy server.

If you use a proxy server in front of the AWS devices you want to communicate with, enter values in the proxy fields. Otherwise, you can skip these fields.

Click Save & Close.

Defining an AWS IAM Credential

You can use IAM policies in AWS to restrict which regions and services SL1 will monitor. To do this, you can create another IAM policy and apply that along with the SL1 monitoring policy to the applicable user or role(s).

SL1 includes an AWS IAM credential type that you can use to connect with the AWS service during guided discovery using the IAM discovery method. This credential type uses field names and terminology that are specific to the AWS service.

For more information about monitoring AWS using IAM permissions, see the section on Using IAM Permissions to Restrict SL1 Access to Specific Regions and Services.

To define an AWS IAM credential:

Go to the Credentials page (Manage > Credentials).
Click the Create New button and then select Create AWS IAM Credential. The Create Credential modal page appears:

Supply values in the following fields:

Name. Type a unique name for the credential. Can be any combination of alphanumeric characters, up to 64 characters.
All Organizations. Toggle on (blue) to align the credential to all organizations, or toggle off (gray) and then select one or more specific organizations from the Select the organizations the credential belongs to drop-down field to align the credential with those specific organizations.

To learn more about credentials and organizations, see the section Aligning Organizations With a Credential.

Timeout (ms). Type the time, in milliseconds, after which SL1 will stop trying to communicate with the device from which you want to retrieve data.
AWS Access Key ID. Type the Access Key ID for an account on the AWS device to be monitored.
AWS Secret Access Key. Type the Secret Access Key for an account on the AWS device to be monitored.
Cloud Type. Select the AWS cloud type that will be accessed with the credential. This field is required. Choices are:

Standard. Select this option if you want to connect to a standard AWS account.
GovCloud. Select this option if you want to connect to an AWS GovCloud account.

Configuration. Ignore this setting when using guided discovery as the PowerPack will automatically determine which regions will be utilized.

Regions. Type the AWS regions that you want to discover. For example, entering "ap-southeast-2, us-east-2" will discover two regions. If left blank, all regions will be discovered. To restrict discovery of a region, type a "!" in front of the region, for example, Regions: !us-east-1. The default value is "ALL".
Filter by Tags. To discover AWS devices and filter them by tags, type the tag operation, tag key, and tag value, in the following format: <operation>#<tag name>#<tag value>. For example, if you want to filter by Tag Name, you would type the following:

Tags:equals#Name#Example

Valid operations include:

equals
notEquals
contains
notContains

You can chain together multiple filters separating them by a comma. For example:

Tags:equals#Name#Example,contains#Owner#Someone

Proxy Hostname/IP. Type the host name or IP address of the proxy server.
Proxy Port. Type the port number on the proxy server to which you will connect.
Proxy User. Type the username to use to access the proxy server.
Proxy Password. Type the password to use to access the proxy server.

If you use a proxy server in front of the AWS devices you want to communicate with, enter values in the proxy fields. Otherwise, you can skip these fields.

Click Save & Close.

Completing the Discovery Session

Once you have finished creating or configuring your credential and have selected it in the Credential Selection page, click Next. The Discovery Session Name page appears.

Complete the following fields:

Discovery Session Name. Type a name for the discovery session.
Select the organization to add discovered devices to. Select the name of the organization to which you want to add the discovered device.
Collector Group Name. Select an existing collector group to communicate with the discovered device. This field is required.

When assigning devices to a collector group, SL1's multi-tenancy rules will validate that the collector group you select belongs to the organization you selected in the previous field. If you attempt to run a discovery session where the devices, collector group, and credentials do not all belong to the same organization, you will receive an error message and will not be able to save or execute the discovery session.

Click Next. SL1 creates the AWS root device with the appropriate Device Class assigned to it and aligns the relevant Dynamic Applications. he Device Discovery Completed page appears, which is the third and final step of the guided discovery session. In SL1 version 11.2.0 and later, as SL1 discovers your devices, system messages relating to the discovery appear on the page under the heading "Discovery Logs".

If SL1 cannot determine the appropriate Device Class, it will assign the device to the Generic SNMP Device Class.

Click Close.

The results of a guided discovery do not display on the Discovery Sessions page (Devices > Discovery Sessions). However, you can retrieve details of saved Guided Discovery Sessions with the guidedDiscoverySessions GraphQL query. Details for discovery sessions that create a virtual root device are not currently displayed in the user interface.