Configuring the Environment

AWS Pre-Configuration

The Foglight Agent Manager (FglAM) must run on an EC2 instance in the same VPC as the DocumentDB clusters to be monitored. For connecting a new DocumentDB cluster to a new or existing Foglight Agent Manager, see Connect Amazon EC2 automatically. Create an EC2 instance on which to install and run the new FglAM in step 1. Skip this step in the case of an existing Agent Manager. For connecting an existing DocumentDB cluster to a new or existing Foglight Agent Manager, see Connect Amazon EC2 manually. Create an EC2 instance on which to install and run the new FglAM in step 1. Skip this step in the case of an existing Agent Manager.

Configuring an SSL Connection

These instructions show the pre-configuration steps for configuring the Agent Manager when TLS is enabled on the DocumentDB cluster.

  1. Follow steps 1 and 2 of the Java instructions on Connecting with TLS Enabled to download the AWS certificate authority file and generate a truststore.
  2. Edit the file baseline.jvmargs.config in the directory <FglAM-install-root>/state/default/config. Add the following parameters with file paths and passwords appropriate to your system.
vmparameter.0 = "-Djavax.net.ssl.trustStore=/path/to/truststore";
vmparameter.1 = "-Djavax.net.ssl.trustStorePassword=changeit";

      Escape any quotes with a backslash (’\’).

      On an Agent Manager installed on Windows, use forward slashes in the file paths, like so:

vmparameter.0 = "-Djavax.net.ssl.trustStore=\"C:/path/to/truststore\"";
  1. Restart the FglAM to load the modified VM parameters. Continue with the agent configuration.

Access

The Foglight for DocumentDB agent will be configured with a cluster/instance address, consisting of a host URL and a port. Further, the agent requires two credentials to monitor the DocumentDB environment: an IAM access key with specific permissions, and a database user.

Instance Address

Connection details for only one instance in the cluster need be supplied to configure the agent. The agent will discover the remaining instances and configure all connections automatically. The instance host and port can be retrieved from the AWS Console. Navigate to DocumentDB, then Clusters. Select the cluster identifier and navigate to Connectivity & Security. Copy the host and port from one of the “Connect to this cluster with…” fields.

IAM User

To create an IAM user with the correct permissions, perform the following steps.

  1. Open the AWS Management Console and navigate to IAM, then Users.
  2. Click on the Create user button.
  3. Specify a username and click Next. The user does not need access to the AWS Management Console.
  4. There is no need to add the user to any new or existing group. Click Next, then Create user.
  5. Select the new user from the Users table.
  6. Customize the Resource entry in the following policy statement by replacing “<account>” with your AWS account number. The first asterisk corresponds to a region, the second to a resource type, and the third to a resource identifier. For simplicity, the entire section can also be replaced with the less specific “Resource”: “”*. (The Sid value is arbitrary and an alternate value may be chosen.)
{
    "Sid": "DocDBClusterReadAccess",
    "Effect": "Allow",
    "Action": [
        "rds:DescribeDBClusters",
        "rds:DescribeDBInstances",
        "rds:DescribeGlobalClusters",
        "cloudwatch:ListMetrics",
        "cloudwatch:GetMetricStatistics"
    ],
    "Resource": [
        "arn:aws:rds:*:<account>:*:*"
    ]
}
  1. Select the Permissions tab, then click the Add permissions dropdown, and select Create inline policy.
  2. Under the Policy editor section, click JSON, and replace the empty/template statement (contained in curly brackets) with the statement customized in step #6. above.
  3. Set the policy name (e.g. “DocDBClusterReadAccess”) and click Create policy.
  4. Repeat steps #6.-#9. for elastic clusters, using the following policy statement elastic clusters access.
{
    "Sid": "DocDBElasticReadAccess",
    "Effect": "Allow",
    "Action": [
        "docdb-elastic:ListClusters",
        "docdb-elastic:GetCluster"
    ],
        "arn:aws:rds:*:<account>:*:*"
}
  1. Select the Permissions tab, then click the Add permissions dropdown, and select Create inline policy.
  2. Under the Policy editor section, click JSON, and replace the empty/template statement (contained in curly brackets) with the statement customized in step #10 above.
  3. Set the policy name (e.g. “DocDBElasticReadAccess”) and click Create policy.

Access Key

To create an access key to collect monitoring data from AWS services, perform the following steps.

  1. Open the AWS Management Console and navigate to IAM, then Users.
  2. Select the monitoring user created in the section IAM User above. Under summary, click Create access key (also available under Security credentials > Access keys > Create access key).
  3. Select the use case Third-party service, check the Confirmation checkbox, and click Next.
  4. Optionally provide a description tag, and click Create access key.
  5. Copy the Access key and Secret access key, then click Done.
  6. Configure the agent with the keys, according to the Setting the AWS Connection section.

Database User

The DocumentDB agent requires database user credentials with certain minimum privileges in order to be able to fully monitor the server and cluster. All user authorizations must be for the admin database.

For core monitoring functionality, a user on the admin database with clusterMonitor and readAnyDatabase roles is required. Such a user can be created with the following mongosh code. Be sure to replace your desired username and password before executing:

db.getSiblingDB('admin').createUser({
    user: 'foglightAgent',
    pwd: '<xxxx>',
    roles: ['clusterMonitor', 'readAnyDatabase']
})

An additional custom privilege is required for monitoring users and roles. The following mongosh code can be used to create such a role with this privilege and grant it to the monitoring user. Again, be sure to change the username used below if using something other than foglightUser:

db.getSiblingDB('admin').createRole({
    role: 'viewAllUsersAndRoles',
    privileges: [{ resource: { db: '', collection: '' }, actions: ['viewUser', 'viewRole'] }],
    roles: []
})
db.getSiblingDB('admin').grantRolesToUser('foglightAgent', ['viewAllUsersAndRoles'])