Installing the Network Discovery Docker image - Adaptive Applications - BlueCat Gateway - 24.1.2

Network Discovery Administration Guide
ft:locale
en-US
Product name
BlueCat Gateway
Version
24.1.2

When installing Network Discovery, you'll be deploying it as a single Docker container or as part of multiple Docker containers, with an extensive set of settings and parameters. Several sets of Docker parameters are optional or are needed only for specific system configurations. We recommend you review all available options described below, then construct and customize the Docker command separately before you start.

There are two main system configurations for deploying Network Discovery.

  • Single Container: Both the Network Discovery Management UI and Discovery Probes are run from the same container.

    If you use this strategy, you will deploy only one container. Both the discovery probes and Network Discovery's Management features will be run from the same instance.

  • Multiple Containers: Each probe is deployed in a separate Network Discovery container, managed by a single deployment of Network Discovery in another ("Management") container.

    If you use this strategy, you will need to deploy one (1) Manager container and one (1) additional container for each probe. We recommend you give a descriptive Docker name for each container (like "multi_manager", "multi_probe1", and "multi_probe2") to make it clear which is which.

    Note: After deploying the containers, you'll also need to add each probe container to the probe list within the Management instance.
Tip: After deployment of any container, you can edit most of these settings in the Network Discovery UI, or within Network Discovery configuration files.

Deploying a Docker container

You can deploy the Gateway Docker container from the provided image either on a machine that has a direct connection to the Internet or on a machine that does not have a direct connection to the Internet.

  • If you want to deploy Network Discovery on a machine that has a direct connection to the Internet, do the following:

  1. From the Linux console of the machine, run the following command:

    docker login quay.io

  2. At the prompt, enter your Quay user name and password obtained when generating the encrypted Password.

  3. Mount the relevant directories of the Docker container to persist container data. This is important because starting in Network Discovery v24.1, configuration files are lost during container upgrades or patches. Use either named volumes or bind mounts as described below to ensure that existing data is retained and can be re-imported if you want to migrate to a new release (from v24.1 to later versions). For more information about volumes and bind mounts, refer to the Docker documentation.

    Do one of the following:

    • To mount data by using named volumes:

      Create the required volumes:
      Note: This step is optional because if you start a container with a volume that doesn't exist, the volume is automatically created.
      docker volume create network_discovery_config
docker volume create network_discovery_data
docker volume create network_discovery_output

    • To mount data by using bind mounts:

      Create directories in your host machine and set the appropriate permissions for them:
      mkdir <path>/network_discovery_config
mkdir <path>/network_discovery_data
mkdir <path>/network_discovery_output

chmod -R 755 <path>/network_discovery_config
chmod -R 755 <path>/network_discovery_data
chmod -R 755 <path>/network_discovery_output
  4. Run the Docker container, replacing the indicated fields with appropriate values. Use one of the following commands based on whether you're mounting data by using named volumes or bind mounts:
    Note: To configure the Discovery Probe to operate independently of BAM, add the WORK_WITH_BAM variable in the following command and set the value to false. See Standalone Discovery Probe configuration for details.

    • For named volumes:

      docker run -d --name <image_name> -p <HTTP_PORT>:8000 -p <HTTPS_PORT>:44300 \
-v network_discovery_config:/portal/builtin/workflows/NetworkDiscovery/config/ \
-v network_discovery_data:/portal/builtin/workflows/network_discovery/data/ \
-v network_discovery_output:/portal/builtin/workflows/network_discovery/output/ \
-e BAM_IP=<BAM_IP> \
-e BAM_API_VERSION=2 \
-e SESSION_COOKIE_SECURE=false \
quay.io/bluecat/network_discovery:24.1.2

    • For bind mounts:

      docker run -d --name <image_name> -p <HTTP_PORT>:8000 -p <HTTPS_PORT>:44300 \
-v <path>/network_discovery_config:/portal/builtin/workflows/NetworkDiscovery/config/ \
-v <path>/network_discovery_data:/portal/builtin/workflows/network_discovery/data/ \
-v <path>/network_discovery_output:/portal/builtin/workflows/network_discovery/output/ \
-e BAM_IP=<BAM_IP> \
-e BAM_API_VERSION=2 \
-e SESSION_COOKIE_SECURE=false \
quay.io/bluecat/network_discovery:24.1.2

    Refer to step 7 in the following section for details on these parameters.

    Running this command will automatically trigger a download of the image (docker pull) from the public repository (Quay) if the image is not yet available in the local Docker repository.

  5. From Gateway, confirm that the deployment was successful. For more details, see Verifying docker deployment.

  • If you want to deploy Network Discovery on a machine that does not have a direct connection to the Internet, do the following:

  1. From the Linux console of a separate machine that has a connection to the internet, run the following command:

    docker login quay.io

  2. At the prompt, enter your Quay user name and password obtained when generating the encrypted Password.

  3. Download the latest Network Discovery Adaptive Application file from the public repository (Quay) into the local Docker repository by using the following command:

     docker pull quay.io/bluecat/network_discovery:24.1.2

  4. Run the following command to save the Docker image as a .tar file:

    docker save -o <path_for_generated_tar_file> quay.io/bluecat/network_discovery:24.1.2

  5. Copy the file to the machine that will run Network Discovery. On that machine, run the following command to load the image from the file into the local Docker repository: 

    docker load -i <generated_tar_file>

  6. Mount the relevant directories of the Docker container to persist container data.

    This is important because starting in Network Discovery v24.1, configuration files are lost during container upgrades or patches. Use either named volumes or bind mounts as described below to ensure that existing data is retained and can be re-imported if you want to migrate to a new release (from v24.1 to later versions). For more information about volumes and bind mounts, refer to the Docker documentation.

    Do one of the following:

    • To mount data by using named volumes:

      Create the required volumes:
      Note: This step is optional because if you start a container with a volume that doesn't exist, the volume is automatically created.
      docker volume create network_discovery_config
docker volume create network_discovery_data
docker volume create network_discovery_output

    • To mount data by using bind mounts:

      Create directories in your host machine and set the appropriate permissions for them:
      mkdir <path>/network_discovery_config
mkdir <path>/network_discovery_data
mkdir <path>/network_discovery_output

chmod -R 755 <path>/network_discovery_config
chmod -R 755 <path>/network_discovery_data
chmod -R 755 <path>/network_discovery_output
  7. Run the Docker container, replacing the indicated fields with appropriate values. Use one of the following commands based on whether you're mounting data by using named volumes or bind mounts:
    Note: To configure the Discovery Probe to operate independently of BAM, add the WORK_WITH_BAM variable in the following command and set the value to false. See Standalone Discovery Probe configuration for details.

    • For named volumes:

      docker run -d --name <image_name> -p <HTTP_PORT>:8000 -p <HTTPS_PORT>:44300 \
-v network_discovery_config:/portal/builtin/workflows/NetworkDiscovery/config/ \
-v network_discovery_data:/portal/builtin/workflows/network_discovery/data/ \
-v network_discovery_output:/portal/builtin/workflows/network_discovery/output/ \
-e BAM_IP=<BAM_IP> \
-e BAM_API_VERSION=2 \
-e SESSION_COOKIE_SECURE=false \
quay.io/bluecat/network_discovery:24.1.2

    • For bind mounts:

      docker run -d --name <image_name> -p <HTTP_PORT>:8000 -p <HTTPS_PORT>:44300 \
-v <path>/network_discovery_config:/portal/builtin/workflows/NetworkDiscovery/config/ \
-v <path>/network_discovery_data:/portal/builtin/workflows/network_discovery/data/ \
-v <path>/network_discovery_output:/portal/builtin/workflows/network_discovery/output/ \
-e BAM_IP=<BAM_IP> \
-e BAM_API_VERSION=2 \
-e SESSION_COOKIE_SECURE=false \
quay.io/bluecat/network_discovery:24.1.2

    Where:

    Parameter Description
    <NAME>

    <HTTP_PORT>

    <HTTPS_PORT>

    <NAME>: Docker name

    <HTTP_PORT>: The HTTP port for BlueCat Gateway

    <HTTPS_PORT>: The HTTPS port for BlueCat Gateway
    <BAM_IP> The IP or FQDN for BlueCat Address Manager
    <BAM_API_VERSION> API version of BlueCat Address Manager. Only version 2 is supported; if you skip this field, 2 will be automatically applied as the API version.
    <SESSION_COOKIE_SECURE> If true (the default), Network Discovery will restrict its functions to HTTPS locations and addresses. If false, Network Discovery will operate on both HTTP and HTTPS.
    Optional configuration parameters: If needed, include the following configuration parameters in your docker command.
    Important: Parameters specified in the docker run command override settings made in configuration files. To change parameters specified in the docker run command, you must delete and recreate the container.
    -e SSH_USERNAME=<SSH_USER> -e SSH_PASSWORD=<SSH_PASS> \
-e MGMT_URL=<MGMT_URL>
-e MGMT_USERNAME=<MGMT_USER> -e MGMT_PASSWORD=<MGMT_PASS>\
-e MGMT_INTERVAL=<INTERVAL> \
-e DISCOVERY_PROBE_LIST='<discovery_probes>' \
-e EXTERNAL_DISCOVERY_LABEL=<external_discovery_label> \
-e LOG_LEVEL=<log_level> -e MAXBYTES=<max_bytes> -e BACKUPCOUNT=<backup_count> \
    Where:
    Parameter Description

    <SSH_USER>

    <SSH_PASS>

    Optional parameters to set the SSH username and password.

    <SSH_USER>: The SSH username

    <SSH_PASS>: The SSH encrypted password
    <MGMT_URL> The URL for the Management instance.

    <MGMT_USER>

    <MGMT_PASS>

    The account for logging in to the Management instance.

    <MGMT_USER>: The username for logging in to the Management instance.

    <MGMT_PASS>: The encrypted password for logging in to the Management instance.
    <INTERVAL> The management interval for scanning and deleting discovery log and status files, in minutes
    <discovery_probes> The Discovery Probe List, in JSON format on a single line. For more details, see Discovery probe list (JSON format).
    Tip: Manipulation of the Discovery Probe JSON file is typically done only during scripted and customized actions, such as automating deployment of Network Discovery probes. Most users can simply add new probes using the Network Discovery UI.
    <external_discovery_label> The external discovery label, as listed in the external_discoveryUser-defined field (UDF) in Address Manager

    <log_level>

    <max_bytes>

    <backup_count>

    Settings that determine Network Discovery logging behaviour:

    <log_level>: The integer level at which logging should take place.

    <max_bytes>: The maximum number of bytes for the log file.

    <backup_count>: The number of backups to make.

    Optional troubleshooting folder parameters: We recommend you mount additional folders to the host to ease future maintenance and troubleshooting. To do so, include the following parameters in your docker command: 
    -v <GATEWAY_LOG_DIR>:/logs/ \
-v <GATEWAY_WORKSPACE>:/bluecat_gateway/ \
-v <DISCOVERY_LOG_DIR>:/builtin/workflows/network-discovery/logs/
-v <DISCOVERY_INPUT_DIR>:/builtin/workflows/network-discovery/data/ \ 
-v <DISCOVERY_OUTPUT_DIR>:/builtin/workflows/network-discovery/output/ \
    Where:
    Field Description
    <GATEWAY_LOG_DIR> Path for BlueCat Gateway logs.
    <GATEWAY_WORKSPACE> Path for the standard Gateway workspace.
    <DISCOVERY_LOG_DIR> Path for Discovery logs.
    <DISCOVERY_INPUT_DIR> Path for Discovery input data.
    <DISCOVERY_OUTPUT_DIR> Path for Discovery output data (such as JSON files and log files).

  8. From Gateway, confirm that the deployment was successful. For more details, see Verifying docker deployment.

Resolving deployment errors

Typically, you can resolve errors by editing settings in Network Discovery's configuration files. For more details, see Edit and adjust configuration files and settings and Adding a discovery probe. The following table lists the solutions to resolve errors in specific areas:

Area Solution
Discovery Probe credentials

Check and correct the API username, API password, probe label, and probe URL settings.
BAM SSH Connection

Check and correct the BAM SSH username and BAM SSH password settings.
Management Connection

Check and correct API username, API password, and Management URL for remote probe fields.
BAM SSH Connection and Management Connection

Check and correct the BAM SSH username, BAM SSH password, API username, API password, and Management URL for remote probe fields.
If probes have stopped

In the Swagger API documentation for the corresponding container, run the following API (Discovery Probe Resource section for v2 REST API):

POST.../ discovery_probe/start

When you've finished resolving the errors, click Submit.