Configuring Docker Observer jobs

Using the Docker Observer, you can discover Docker network resources, including Docker Swarm clusters, and then visualize (or model) this data as a topology view in the Agile Service Manager UI. You configure observer jobs from the Observer Configuration UI.

Before you begin

Important: The Docker Observer supports Docker version 3.1.0.
Note: Docker UCP v3.1.0 supports only TLS 1.2 for SSL negotiation and has removed support for TLS 1 and TLS 1.1.

Ensure you have the details for your Docker job to hand, specifically your Docker system's Unix socket, and / or host and port number.

The Docker Observer is installed as part of the core installation procedure.

Update Notes: If you have updated a previous version of Agile Service Manager with existing Docker Observer job data, you must run a data migration script (documented in the on-prem update topic) before running new observer jobs.

About this task

Using the Observer Configuration UI you configure observer jobs that query the Docker REST API to retrieve data and display it as a topology in the Topology Viewer. The Docker Observer can model external Docker systems.

The job parameters determine whether to connect to a local Docker on the same (UNIX) host as the observer using the unix_socket parameter, or to a remote Docker using the host and port parameters.

Table 1. Docker Observer job parameters
Parameter Action Details
Unique ID Enter a unique name for the job Required
Host Use this to identify the TCP host socket (HTTP or HTTPS) on which to access the remote Docker system. Required for remote Docker access only
Username Specify the username of the remote Docker environment with HTTPS. Required for remote Docker with HTTPS access only.
Password Specify the password of the remote Docker environment with HTTPS. Required for remote Docker with HTTPS access only. Accepts plain text or encrypted versions.
Docker SSL Certificate Specify the certificate file name.

Required for remote Docker with HTTPs access only.

Required. For more information, see Configuring observer job security.
On-premises
Create and store the certificate in the ASM_HOME/security directory.
OpenShift Container Platform
Obtain the authentication certificate by using OpenSSL and store it as a secret.
Docker SSL TrustStore File Specify the trustStore file name.
Tip: You can use the observer name (<observer>.jks) for example docker.jks.
 Required for remote Docker with HTTPs access only. For both on-prem and OCP, provide the JKS name, and the observer will then create the JKS file accordingly.
SSL TrustStore File Password Specify the trustStore password. Required for remote Docker with HTTPS access only. Accepts plain text or encrypted versions.
Port Use this to identify the TCP port (HTTP or HTTPS) on which to access the remote Docker system. Required for remote Docker access only
Unix Socket Use this to access local docker environments using the complete path. Required for local Docker access only. Host and port parameters must be empty.
View Use this to select which resources are modeled in the topology view. Optional. The Default displays running resources only. Options are:
Container
All running containers
Image
Images used by running containers
Task
Running tasks only
Containers to exclude List container you want to exclude. Optional
Access scope

Enter text to provide a scope for the resources.

Access scope can help map alerts to resources when resources in different scopes share parameters, such as matchTokens.

 Optional.
Tip: You can define access scope for locations, project names, namespaces, and so on.
Generate debug support file
Set the optional Generate debug support file parameter to True to capture the output of the next scheduled job run as a file. This file is stored with an observer's log files and can be used to debug observer issues, for example at the request of your designated Support team, or while using a test environment. For one-off jobs (that is, Load jobs), this parameter reverts to False after the next completed run. To examine the output produced, you can load the generated debug file using the File Observer. The file is saved to the following locations:
On-premises
$ASM_HOME/logs/<obs>-observer/
On OpenShift Container Platform
/var/log/itsm/<obs>-observer
 Optional
Observer job description Enter additional information to describe the job. Optional
Job schedule

Specify when the job should run, and whether it should run at regular intervals.

By default the job runs immediately, and only once.

Optionally you can specify a future date and time for the job to run, and then set it to run at regular intervals after that.

Optional. Transient (one-off) jobs only.

If you set a job schedule, the run intervals must be at least 90 seconds apart. If you set them at less than 15 minutes, a warning is displayed, as the frequency can impact system performance.
SSL requirements: To acquire SSL certificates and build SSL truststores, use the relevant instructions in the following section: Configuring observer job security

Procedure

  1. On the Observer jobs page, perform one of the following actions:
    To edit an existing job
    Open the List of options overflow menu next to the job and click View & edit.
    To create a new job
    Click Add a new job + and select the Docker Observer tile.
  2. Configure one of the following job types.
    • To discover remote Docker network resources through TCP port exposure, enter or edit the following parameters:
      • Unique ID
      • Host
      • Port
      • View (optional)
      • Containers to exclude (optional)
      • Job description (optional)
    • To discover remote Docker network resources through HTTPS, enter or edit the following parameters:
      • Unique ID
      • Host
      • Port
      • Username
      • Password
      • Docker SSL Certificate
      • Docker SSL TrustStore File
      • SSL TrustStore File Password
      • View (optional)
      • Containers to exclude (optional)
      • Job description (optional)
    • To discover local Docker networks (if the Unix socket is accessible via the Docker container), enter or edit the following parameters:
      • Unique ID
      • Unix socket
      • View (optional)
      • Containers to exclude (optional)
      • Job description (optional)
      Restriction: For local Docker networks, the host and port parameter fields must be empty.
  3. Optional: Define a Job schedule (for Load jobs only) by setting the time when the job should run, and whether it should run at regular intervals. By default, the job runs immediately, and only one time.
    If required, you can specify a future date and time for the job to run, and then set it to run at regular intervals after that. The run intervals must be at least 90 seconds apart, and if you set them at less than 15 minutes, a warning is displayed, as the frequency can impact system performance.
  4. Optional: Enter an Observer job description to explain the purpose of the job in more detail.
  5. Click Save to save your job and begin retrieving information.