Configuration and Discovery

The following sections describe how to configure and discover the Docker platform and its component devices for monitoring by SL1 using the Docker PowerPack:

Prerequisites for Monitoring Docker

If you are using Secure Shell (SSH) to monitor Docker or Kubernetes nodes in conjunction with the Kubernetes PowerPack, you must install cURL 7.40 or greater on all of the Docker hosts that you want to monitor, prior to discovery. You must then run the following cURL commands on each of those hosts:

curl --unix-socket /var/run/docker.sock http://docker/containers/json
curl --unix-socket /var/run/docker.sock http://docker/containers/\[container_id]/json
curl --unix-socket /var/run/docker.sock http://docker/containers/\[container_id]/stats?stream=0

If you are using a Basic/Snippet credential, before you can monitor the Docker platform and its component devices in SL1 using the Docker PowerPack, you must first follow the instructions in the Enabling the Docker API section. These steps enable the Dynamic Applications in the Docker PowerPack to communicate with and gather data from the Docker API.

NOTE: You do not need to enable the API if you are using SSH to monitor Docker.

If you choose to enable the API when monitoring Docker versions through 18.06.1-ce-rc2, be aware that a vulnerability exists. The API endpoints behind the 'docker cp' command are vulnerable to a symlink-exchange attack. (CVE-2018-15664).

Enabling the Docker API

Before you discover Docker components using the Docker PowerPack, you must first enable the Docker API. This section describes how to do so for Windows, CentOS, Red Hat Enterprise Linux (RHEL), and Oracle Linux operating systems.

NOTE: If you are using SSH to monitor Docker, skip this section and go to the Creating an SSH/Key Credential section.

Windows

To enable the Docker API for Windows using the Docker Toolbox:

Start Docker Quickstart Terminal.

To determine the IP address of the Docker host machine, type the following command:

$ docker-machine ip

$ docker-machine ssh

Navigate to Boot2Docker:

$ cd /var/lib/boot2docker

Edit the Boot2Docker profile:

$ sudo vi profile

In the profile, change "DOCKER_HOST" to "DOCKER_HOST='-H tcp://0.0.0.0:[port number]'", and set DOCKER_TLS=no.

Exit the SSH session, and then restart Docker:

$ exit

$ docker-machine restart

To verify that the Docker API is accessible, open a browser and navigate to http:[IP address]:[port number]/version.

If the Docker API is successfully enabled, the version returns something similar to the following:

{"Version":"17.10.0-ce","ApiVersion":"1.33","MinAPIVersion":"1.12","GitCommit":
"f4ffd25","GoVersion":"go1.8.3","Os":"linux","Arch":"amd64","KernelVersion":
"4.4.93-boot2docker","BuildTime":"2017-10-17T19:05:23.000000000+00:00"}

CentOS

To enable the Docker API for CentOS:

$ cd /etc/systemd/system

Create a new "docker.service.d" folder, then navigate to that folder:

$ mkdir docker.service.d

$ cd docker.service.d

Create a new docker.conf file:

$ vi docker.conf

Type the following:

INSERT

[Service]

ExecStart=

ExecStart=/usr/bin/dockerd -H tcp://0.0.0.0:[port number] -H unix://var/run/docker.sock

Reload daemon, restart Docker, and open the port on the firewall by typing the following:

$ systemctl daemon-reload

$ systemctl restart docker

$ firewall-cmd --add-port=[port number]/tcp

Verify that the Docker API is accessible by typing the following:

$ *curl http://localhost:[port number]/version*

If the Docker API is successfully enabled, the version returns something similar to the following:

{"Version":"17.06.1-ce","ApiVersion":"1.30","MinAPIVersion":"1.12","GitCommit"
:"874a737","GoVersion":"go1.8.3","Os":"linux","Arch":"amd64","KernelVersion":
"3.10.0-514.26.2.el7.x86_64","BuildTime":"2017-08-17T23:01:50.155177940+00:00"}

RHEL 7 and Oracle Linux 7

To enable the Docker API for RHEL 7 or Oracle Linux 7:

$ cd /etc/systemd/system

Edit the service.docker file:

$ sudo vi docker.service

Create or edit the file to ensure that it has a [Service] section and a line that starts with "ExecStart=/usr/bin/dockerd". Add "-H tcp://0.0.0.0:[port number] -H unix:///var/run/docker.sock" so that the updated line looks like this:

ExecStart=/usr/bin/dockerd -H tcp://0.0.0.0:4243 -H unix:///var/run/docker.sock

Open the firewall port, if needed, and then reload daemon and restart restart Docker by typing the following:

$ sudo firewall-cmd --add-port=[port number]/tcp

$ sudo firewall-cmd --reload

$ sudo systemctl daemon-reload

$ sudo systemctl restart docker

Verify that the Docker API is accessible by typing the following:

$ curl http://[IP address]:[port number]/version

If the Docker API is successfully enabled, the version returns something similar to the following:

{"Version":"17.06.2-ee-4","ApiVersion":"1.30","MinAPIVersion":"1.12","GitCommit":
"dd2c358","GoVersion":"go1.8.3","Os":"linux","Arch":"amd64","KernelVersion":
"3.10.0-514.el7.x86_64","BuildTime":"2017-10-12T16:19:56.386620861+00:00"}

NOTE: For Linux distributions, some versions of the firewall require the "--permanent" flag. This is likely the case if the first attempt at automatic discovery fails and manually aligned Dynamic Applications are not collecting.

Configuring a Docker Credential

The Docker PowerPack includes an example Basic/Snippet Credential and an example SSH/Key Credential for your use. You can modify these to create your own Credentials that will enable SL1 to discover your Docker devices.

Creating a Basic/Snippet Credential

To configure SL1 to monitor the Docker platform using the Docker API, you must create a Basic/Snippet credential that allows the Dynamic Applications in the Docker PowerPack to connect with Docker hosts or swarms. An example Basic/Snippet credential that you can edit for your own use is included in the Docker PowerPack.

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 create a Basic/Snippet credential to access Docker hosts or swarms:

Go to the Credentials page (Manage > Credentials).
Locate the example Docker Basic credential, click its Actions icon () and select Duplicate. A copy of the credential, called Docker Basic copy appears.
Click the Actions icon () for the Docker Basic copy credential and select Edit. The Edit Credential modal page appears:

Supply values in the following fields:

Name. Type a new name for the Docker 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). Type "10000".

Hostname/IP. Type "%D".
Port. Type the port number you specified when you enabled the Docker API.

Username. Type a value for the username.
Password. Type a value for the password.

The Docker platform does not require a specific username and password to access the platform, but SL1 does require the Username and Password fields to have values when using Basic/Snippet credentials to monitor Docker. Therefore, those fields must have entries, but the values themselves do not matter.

Click the Save & Close button.

Creating a Basic/Snippet Credential in the SL1 Classic User Interface

To create a Basic/Snippet credential to access Docker hosts or swarms:

Go to the Credential Management page (System > Manage > Credentials).
Locate the example Docker Basic credential, and then click its wrench icon (). The Edit Basic/Snippet Credential modal page appears.

Complete the following fields:

Credential Name. Type a new name for the Docker credential.

Hostname/IP. Type "%D".
Port. Type the port number you specified when you enabled the Docker API.
Timeout(ms). Type "10000".

Username. Type a value for the username.
Password. Type a value for the password.

Click the Save As button.
When the confirmation message appears, click OK.

Creating an SSH/Key Credential

If you are using SSH to monitor Docker swarms, then you must create an SSH/Key credential that allows the Dynamic Applications in the Docker PowerPack to connect with Docker swarms. An example SSH/Key credential that you can edit for your own use is included in the Docker PowerPack.

You can also use an SSH credential in conjunction with the Kubernetes PowerPack to monitor the Docker infrastructure for a Kubernetes cluster.

To create an SSH/Key credential to monitor Docker containers:

Go to the Credentials page (Manage > Credentials).
Locate the example Docker Basic - SSH credential, click its Actions icon () and select Duplicate. A copy of the credential, called Docker Basic - SSH copy appears.

Click the Actions icon () for the Docker Basic - SSH copy credential and select Edit. The Edit Credential modal page appears:

Name. Type a new name for the Docker 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). Type "10000".

Hostname/IP. Type "%D".
Port. Type the SSH port number for the Docker swarm you want to monitor.

Username. Type the username for a user with SSH access to the Docker swarm command line interface.
Password. Type the user's password.
PEM Format. Keep this field blank.

The private key can have a maximum of 64 characters per line. Therefore, you cannot use keys in the OpenSSH format, because that format uses 70 characters per line. When you attempt to save the credential, SL1 will validate that the private key entered is in the correct format. You will be able to save the credential only if the private key is correctly formatted.

Click the Save & Close button.

Creating an SSH/Key Credential in the SL1 Classic User Interface

You can also use an SSH credential in conjunction with the Kubernetes PowerPack to monitor the Docker infrastructure for a Kubernetes cluster.

To create an SSH/Key credential to monitor Docker containers:

Go to the Credential Management page (System > Manage > Credentials).
Locate the example Docker Basic - SSH credential, and then click its wrench icon (). The Edit SSH/Key Credential modal page appears.

Complete the following fields:

Credential Name. Type a new name for the Docker credential.

Hostname/IP. Type "%D".
Port. Type the SSH port number for the Docker swarm you want to monitor.
Timeout(ms). Type "10000".

Username. Type the username for a user with SSH access to the Docker swarm command line interface.
Password. Type the user's password.
Private Key (PEM Format). Keep this field blank.

Click the Save As button.
When the confirmation message appears, click OK.

Discovering Docker Components

To discover and model your Docker component devices for monitoring, you must run a discovery session. The discovery session will discover the Docker hosts and swarms that SL1 will use as the root devices for monitoring the Docker components.

Several minutes after the discovery session has completed, the Dynamic Applications in the Docker PowerPack will automatically align to the Docker root devices. These Dynamic Applications will discover, model, and monitor the remaining components in your Docker system.

To discover Docker components, perform the following steps:

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 Add Devices page appears.
Complete 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 Credentials page of the Add Devices wizard appears:

On the Credentials page, locate and select the Basic/Snippet or SSH/Key credential you created for Docker.

Click Next. The Discovery Session Details page of the Add Devices wizard appears:

Complete the following fields:

List of IPs/Hostnames. Type the IP addresses for all of the Docker hosts in the swarm that you want to discover.

NOTE: Swarms are created only when the swarm leader is discovered. To monitor a Docker Swarm, you must discover all nodes included in the cluster by SSH connections.

NOTE: You must have both Docker Swarms and Docker Hosts (Managers and Workers) discovered on the same Data Collector on which the Docker Swarm Leader is discovered to keep the cache on the Docker Swarm device. If there is maintenance or a failure on the Data Collector that is hosting the Swarm cluster and Docker Hosts, a run book action will move all the Hosts and the Swarm cluster to the same Data Collector that the Leader has been moved to. If a device is moved to a different Data Collector, the same run book action will keep the Host with the Leader. Data gaps in collection may appear during this process.

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.

Discovering Docker Components in the SL1 Classic User Interface

To discover Docker components, perform the following steps:

Go to the Discovery Control Panel page (System > Manage > Classic Discovery), and then click the Create button. The Discovery Session Editor page appears.

In the Discovery Session Editor page, complete the following fields:

Name. Type a name for your discovery session.

IP Address/Hostname Discovery List. Type the IP addresses for all of the Docker hosts in the swarm that you want to discover.

NOTE: Swarms are created only when the swarm leader is discovered. To monitor a Docker Swarm, you must discover all nodes included in the cluster by SSH connections.

Other Credentials. Select the Basic/Snippet or SSH/Key credential(s) you created for Docker.
Discover Non-SNMP. Select this checkbox.
Model Devices. Select this checkbox.

Optionally, you can enter values in the other fields on this page. For more information about the other fields on this page, see the Discovery & Credentials section.
Click the Save button to save the discovery session, and then close the Discovery Session Editor window.
The discovery session you created displays at the top of the Discovery Control Panel page. Click its lightning-bolt icon () to run the discovery session.
The Discovery Session window appears. When a root device is discovered, click its device icon () to view the Device Properties page for that device.

Manually Aligning Dynamic Applications

To verify that SL1 has automatically aligned the correct Dynamic Applications during discovery:

From the Device Investigator page for the Docker root device, click the Collections tab.

The following Dynamic Applications should appear in the list of aligned Dynamic Applications:

For Docker Hosts:

Docker: Container Discovery

Docker: Containers Performance
Docker: Host Configuration
Docker: Host Performance
Docker: Host Reclassification
Docker: Image Configuration
Docker: Image Performance
Docker: Network Configuration
Docker: Swarm Cluster Discovery

For Docker Swarms:

Docker: Stack Discovery

Docker: Swarm Configuration
Docker: Swarm Performance
Docker: Swarm Service Discovery

It can take several minutes after discovery for Dynamic Applications to display on the Dynamic Application Collections page. If the listed Dynamic Applications do not display on this page, try clicking the Reset button.

If the Dynamic Applications have not been automatically aligned, you can align them manually. To do so, perform the following steps:

Go to the Device Investigator page for the Docker root device and click the Collections tab.
Click the Edit button and then click the Align Dynamic App button.On the Dynamic Application Collections page, click the Action button and then select Add Dynamic Application from the menu. The Dynamic Application Alignment page appears.

In the Align Dynamic Application window, click Choose Dynamic Application.
In the Choose Dynamic Application window, select the Dynamic Application you want to align and click Select. The name of the selected Dynamic Application appears in the Align Dynamic Application window.
Uncheck the box next to Use Device SNMP Credential and click Choose Credential. The Choose Credential window appears.
Select the Basic/Snippet credential you created for Docker and then click the Select button. The name of the Docker credential you selected appears in the Align Dynamic Application window.
Click the Align Dynamic App button. When the Dynamic Application is successfully aligned, it is added to the Collections tab, and a confirmation message appears at the bottom of the tab.
Repeat steps 2-7 as needed to align any additional Dynamic Applications.

Viewing Docker Component Devices

In addition to the Devices page, you can view the Docker platform and all of its component devices in the following places in the user interface:

The Device Investigator Map page (click Map in the Device Investigator page) displays a map of a particular device and all of the devices with which it has parent-child relationships. Double-clicking any of the listed devices reloads the page to make the selected device the primary device.

The Device Components page (Registry > Devices > Device Components) displays a list of all root devices and component devices discovered by SL1 in an indented view, so you can easily view the hierarchy and relationships between child devices, parent devices, and root devices. To view the component devices associated with Docker, find the Docker Host or Docker Swarm device and click its plus icon (+):

The Component Map page (Classic Maps > Device Maps > Components) allows you to view devices by root node and view the relationships between root nodes, parent components, and child components in a map. This makes it easy to visualize and manage root nodes and their components. SL1 automatically updates the Component Map as new component devices are discovered. The platform also updates each map with the latest status and event information. To view the map for a Docker device, go to the Component Map page and select the map from the list in the left NavBar. To learn more about the Component Map page, see the section on Maps.

Relationships Between Component Devices

In addition to parent/child relationships between component devices, SL1 also creates relationships between the following component devices:

Swarms and Nodes

Services and Containers

You can also use the Docker PowerPack in conjunction with the Kubernetes PowerPack when monitoring Kubernetes systems. When you do so, SL1 creates relationships between Docker Swarms and Containers and their underlying Kubernetes Nodes.