Add Docker Engine/Docker Container

Step 1: Prepare Docker Engine/Docker Container for monitoring.

Docker Engine/Docker Container Configuration

Docker Engine/Docker Container Configuration
You can configure a Docker Engine for monitoring in three ways: Non-Secure Mode: This mode doesn’t need any credentials information. When the Docker Engine is configured in the non-secure mode (http), you simply need the Base URL to connect to the Docker Engine. For example, a Base URL could be: `http://www.example.com:4243/`. Note the `http`, and not `https` mode. To check if your Docker Engine is configured in non-secure mode, view the `/etc/sysconfig/docker` file. The following entries identify the Non-Secure Mode configuration: `http - non secure other_args="-H tcp://0.0.0.0:4243 -H unix:///var/run/docker.sock" set proxy export HTTP_PROXY=<your proxy host>:80` You will need to provide the Docker Engine Base URL in the entity definition JSON file. Secure Mode: To check if your Docker Engine is configured in Secure Mode, view the /etc/sysconfig/docker file. If configured for: for 1–way SSL you will typically see an entry of the format: `https - secure 1 way SSL other_args="-H tcp://0.0.0.0:4243 -H unix:///var/run/docker.sock --tls --tlscert=/<certificate directory>/server-cert.pem --tlskey=/<certificate directory>/server-key.pem"` for 2–way SSL you will typically see an entry of the format: `https - secure 2 way SSL other_args="-H tcp://0.0.0.0:4243 -H unix:///var/run/docker.sock --tlsverify --tlscacert=/<certificate directory>/ca.pem --tlscert=/<certificate directory>/server-cert.pem --tlskey=/<certificate directory>/server-key.pem"` If your Docker Engine is configured in Secure Mode, then you configure the monitoring credentials based on the type of communication defined. For Secure 1–way SSL you need to add the truststore certificate (CA certificate) in the cloud agent default truststore (`<agent home>/sysman/config/montrust/AgentTrust.jks`) using this command: `keytool -import -alias docker01 -keystore <agent home>/sysman/config/montrust/AgentTrust.jks -file <directory of your Docker certificate>/<certificate_file_name>.cer` Use the password `welcome`. Note the <agent home> is the directory where the Cloud Agent was installed. See Managing Cloud Agents in Oracle® Cloud Deploying and Managing Oracle Management Cloud Agents. You will only need to provide the Docker Engine Base URL in the entity definition JSON file. For Secure 2–way SSL you need to add the truststore certificate (CA certificate) and the keystore information in the agent default truststore (`<agent home>/sysman/config/montrust/AgentTrust.jks`). Add the truststore certificate: `keytool -import -alias docker01 -keystore <agent home>/sysman/config/montrust/AgentTrust.jks -file <directory of your Docker certificate>/<certificate_file_name>.cer` Use the password `welcome`. Note the agent home is the directory where the Cloud Agent was installed. Add the keystore information: `keytool -import -alias docker01 -keystore <agent home>/sysman/config/montrust/AgentTrust.jks -file <directory of your Docker certificate>/<certificate_file_name>.cer` Use the password `welcome`. To add a Secure 2–way SSL Docker Engine entity you will need to create an entity definition JSON file along with a credentials JSON file. The entity definition JSON file will include your Docker Engine Base URL while the credentials file will have details about the credentials store and credentials. For more information about how to create Docker certificates, see https://docs.docker.com/engine/security/https/. Cloud Agent Configuration If the cloud agent communicates with Oracle Management Cloud through a proxy (OMC_PROXYHOST & OMC_PROXYPORT parameters were set on the cloud agent when it was installed), Docker Engine / Docker Container discovery will fail. You’ll need to perform additional configuration steps depending on the following situations: For a New Agent Installation If the agent requires proxy to communicate with Oracle Management Cloud, then use the gateway and set the proxy parameters (OMC_PROXYHOST & OMC_PROXYPORT) during gateway installation, and then set up the cloud agent (without proxy parameters) to point to the gateway. For an Existing Agent If the existing cloud agent has been set up to use the proxy to communicate with Oracle Management Cloud, to discover Docker Engine / Docker Container, execute the following commands on the cloud agent before performing entity discovery. `omcli setproperty agent -allow_new -name _configureProxyPerClient -value true omcli stop agent omcli start agent`

You can configure a Docker Engine for monitoring in three ways:

Non-Secure Mode:

This mode doesn’t need any credentials information. When the Docker Engine is configured in the non-secure mode (http), you simply need the Base URL to connect to the Docker Engine.

For example, a Base URL could be: http://www.example.com:4243/. Note the http, and not https mode.

To check if your Docker Engine is configured in non-secure mode, view the /etc/sysconfig/docker file. The following entries identify the Non-Secure Mode configuration:

http - non secure other_args="-H tcp://0.0.0.0:4243 -H unix:///var/run/docker.sock" 
set proxy export HTTP_PROXY=<your proxy host>:80

You will need to provide the Docker Engine Base URL in the entity definition JSON file.

Secure Mode:

To check if your Docker Engine is configured in Secure Mode, view the /etc/sysconfig/docker file. If configured for:

for 1–way SSL you will typically see an entry of the format:

https - secure 1 way SSL other_args="-H tcp://0.0.0.0:4243 -H unix:///var/run/docker.sock --tls --tlscert=/<certificate directory>/server-cert.pem --tlskey=/<certificate directory>/server-key.pem"

for 2–way SSL you will typically see an entry of the format:

https - secure 2 way SSL other_args="-H tcp://0.0.0.0:4243 -H unix:///var/run/docker.sock --tlsverify --tlscacert=/<certificate directory>/ca.pem --tlscert=/<certificate directory>/server-cert.pem --tlskey=/<certificate directory>/server-key.pem"

If your Docker Engine is configured in Secure Mode, then you configure the monitoring credentials based on the type of communication defined.

For Secure 1–way SSL you need to add the truststore certificate (CA certificate) in the cloud agent default truststore (<agent home>/sysman/config/montrust/AgentTrust.jks) using this command:
```
keytool -import -alias docker01 -keystore <agent home>/sysman/config/montrust/AgentTrust.jks -file <directory of your Docker certificate>/<certificate_file_name>.cer 
```
Use the password welcome. Note the <agent home> is the directory where the Cloud Agent was installed. See Managing Cloud Agents in Oracle® Cloud Deploying and Managing Oracle Management Cloud Agents.

You will only need to provide the Docker Engine Base URL in the entity definition JSON file.
For Secure 2–way SSL you need to add the truststore certificate (CA certificate) and the keystore information in the agent default truststore (<agent home>/sysman/config/montrust/AgentTrust.jks).
1. Add the truststore certificate:
```
keytool -import -alias docker01 -keystore <agent home>/sysman/config/montrust/AgentTrust.jks -file <directory of your Docker certificate>/<certificate_file_name>.cer 
```
  Use the password welcome. Note the agent home is the directory where the Cloud Agent was installed.
2. Add the keystore information:
```
keytool -import -alias docker01 -keystore <agent home>/sysman/config/montrust/AgentTrust.jks -file <directory of your Docker certificate>/<certificate_file_name>.cer
```
  Use the password welcome.
  
  To add a Secure 2–way SSL Docker Engine entity you will need to create an entity definition JSON file along with a credentials JSON file. The entity definition JSON file will include your Docker Engine Base URL while the credentials file will have details about the credentials store and credentials.

For more information about how to create Docker certificates, see https://docs.docker.com/engine/security/https/.

Cloud Agent Configuration

If the cloud agent communicates with Oracle Management Cloud through a proxy (OMC_PROXYHOST & OMC_PROXYPORT parameters were set on the cloud agent when it was installed), Docker Engine / Docker Container discovery will fail. You’ll need to perform additional configuration steps depending on the following situations:

For a New Agent Installation

If the agent requires proxy to communicate with Oracle Management Cloud, then use the gateway and set the proxy parameters (OMC_PROXYHOST & OMC_PROXYPORT) during gateway installation, and then set up the cloud agent (without proxy parameters) to point to the gateway.

For an Existing Agent

If the existing cloud agent has been set up to use the proxy to communicate with Oracle Management Cloud, to discover Docker Engine / Docker Container, execute the following commands on the cloud agent before performing entity discovery.

omcli setproperty agent -allow_new -name _configureProxyPerClient -value true 
omcli stop agent 
omcli start agent

Step 2: Decide how you want to add the Docker Engine/Docker Container.

You can add Docker Engine/Docker Container entities using one of two ways:

Add them from UI
Use the agent's omcli add_entity command with the appropriate JSON files

Adding Entities from the UI

From the Management Cloud main menu, select Administration, Discovery, and then Add Entity. The Add Entity page displays.
Select the Docker Engine/Docker Container Entity Type.

Enter the following UI properties.

Docker Engine/Docker Worker UI Fields
Discover Using Credentials: Discover using Docker Engine credentials (on by default). Entity Name: Your Docker Engine/Container name. Base URL: The base URL for REST API invocations. Host Name: The fully-qualified host name where the Docker Engine/Container is installed. Swarm ID: Unique identifier of the Docker Swarm containing the Docker Engine/Container. Cloud Agent: Cloud agent monitoring the host where the Docker Engine/Container is running. Monitoring Credentials (Docker Engine Credentials) Store Location: The full path to the location of the keystore file. Store Password: The keystore password to access the jks file. Store Type: Currently, only JKS is supported.

Docker Engine/Docker Worker UI Fields

Discover Using Credentials: Discover using Docker Engine credentials (on by default).
Entity Name: Your Docker Engine/Container name.
Base URL: The base URL for REST API invocations.
Host Name: The fully-qualified host name where the Docker Engine/Container is installed.
Swarm ID: Unique identifier of the Docker Swarm containing the Docker Engine/Container.
Cloud Agent: Cloud agent monitoring the host where the Docker Engine/Container is running.

Monitoring Credentials (Docker Engine Credentials)

Store Location: The full path to the location of the keystore file.
Store Password: The keystore password to access the jks file.
Store Type: Currently, only JKS is supported.

See Add Entities from the Console for detailed instructions on using the Add Entity UI.

Using omcli and the Appropriate JSON Files

Download and extract the required JSON file(s) from the master JSON zip file. See the table below for the specific JSON files you'll need.

Edit the file(s) and specify the requisite properties shown below.

Docker Engine/Docker Container JSON Files and Properties

Docker Engine/Docker Container JSON Files and Properties
Definition Files omc_docker_engine_sample.json (used without the omc_docker_engine_sample_creds.json) omc_docker_engine_secure_sample.json (used with the omc_docker_engine_sample_creds.json) name: Your Docker Engine name. displayName: Name displayed in the Oracle Infrastructure Monitoring User Interface. timezoneRegion: Time zone of your entity. It is recommended that you use the long values IANA-maintained TZ database time zones. For example: America/New_York BaseURI: Under “value”, provide the base URL for REST API invocations. host_name: Under “value”, provide the fully-qualified host name where the Docker Engine is installed. Credential File: omc_docker_engine_sample_creds.json StoreLocation: Under “value”, within the square brackets, provide the full path to the location of the keystore file. You must have configured this entity security in the Prerequisite Tasks step. For example, `<agent home>/sysman/config/montrust/AgentTrust.jks` Note that in this release only jks file types are supported. StorePassword: Under “value”, within the square brackets, provide the keystore password to access the jks file. Note that in this release only jksfile types are supported. Do not remove the square brackets.

Definition Files

omc_docker_engine_sample.json (used without the omc_docker_engine_sample_creds.json)

omc_docker_engine_secure_sample.json (used with the omc_docker_engine_sample_creds.json)

name: Your Docker Engine name.
displayName: Name displayed in the Oracle Infrastructure Monitoring User Interface.
timezoneRegion: Time zone of your entity. It is recommended that you use the long values IANA-maintained TZ database time zones. For example: America/New_York
BaseURI: Under “value”, provide the base URL for REST API invocations.
host_name: Under “value”, provide the fully-qualified host name where the Docker Engine is installed.

Credential File: omc_docker_engine_sample_creds.json

StoreLocation: Under “value”, within the square brackets, provide the full path to the location of the keystore file. You must have configured this entity security in the Prerequisite Tasks step. For example, <agent home>/sysman/config/montrust/AgentTrust.jks
Note that in this release only jks file types are supported.
StorePassword: Under “value”, within the square brackets, provide the keystore password to access the jks file.
Note that in this release only jksfile types are supported.

Do not remove the square brackets.

Add the entity using omcli.

omcli add_entity agent DEFINITION_FILE [-credential_file CREDENTIAL_FILE [-encryption_method_gpg]]

Verify the status of the newly added entity.
```
omcli status_entity agent DEFINITION_FILE
```

See step 4. Adding Entities to Your Service of Add Entities Using JSON Files for more information.

Step 3: (Optional but recommended) Set up alerts.

To enable lights-out monitoring, you can set up alert rules to generate alerts and send notifications if your entities have performance issues.

See Set Up Alert Rules and Set Up Alert Thresholds and Notifications.

Troubleshooting

If you run into any issues regarding discovery or monitoring of Docker Engine/Docker Container, see the following: