Using BMC Helix Monitor Agent to collect data

BMC Helix Monitor Agent is a light-weight containerized collector that is pre-configured and is ready to be deployed. It has the following advantages:

  • No Agent configurations are required after deployment.
  • Knowledge modules (KMs) are already deployed within the container.

BMC provides you the following options in BMC Helix Monitor Agent:

  • BMC Helix Monitor Agent-Containerized.
    Monitor multiple environments by using the same Agent
  • Kubernetes multi-node deployment
    Monitor Kubernetes clusters
  • OpenShift multi-node deployment
    Monitor OpenShift clusters


BMC Helix Monitor Agent-Containerized

You can monitor the following knowledge modules by using BMC Helix Monitor Agent-Containerized:


Kubernetes multi-node deployment

This mode focuses on monitoring Kubernetes clusters and is bundled with only PATROL for Kubernetes 22.4.02 and PATROL for Linux 22.4.11. When you deploy this option of BMC Helix Monitor Agent to a Kubernetes cluster, a BMC Helix Monitor Agent container is deployed on each node of the cluster. It facilitates metrics collection from each node and associated pods. 

System requirements


OpenShift multi-node deployment

This mode focuses on monitoring OpenShift clusters and is bundled with only PATROL for OpenShift 24.2.00 and PATROL for Linux 22.4.11. When you deploy this option of BMC Helix Monitor Agent to a OpenShift cluster, a BMC Helix Monitor Agent container is deployed on each node of the cluster. It facilitates metrics collection from each node and associated pods. 

System requirements


Docker registry requirements

Direct access to BMC's Docker Trusted Repository (DTR) at  https://containers.bmc.com  is available. You can also use Local Harbor 2.1 or later synchronized with BMC's Docker Trusted Repository.

Best practice
BMC highly recommends that you install a local repository. A local repository provides the following benefits:

  • Improved performance
    The container images are cached and accessed locally during deployments and upgrades.
  • Security 
    You can implement your own security scan of containers before deployment.
  • Access control
    You can control access to the local repository by using authentication and authorization.
  • Air-gap support
    You can replicate the local repository to support environments that do not have internet access.

For information about installing a local Harbor repository synchronized with the BMC DTR, see Setting-up-a-Harbor-repository.

Important

BMC does not manage any repository other than Harbor and recommends that you use the local Harbor repository to pull the container image. However, if you are using any other repository, make sure that the repository is configured to connect to the BMC DTR to pull the container image.


To use Helix Monitor Agent

  1. Download the BMC Helix Monitor Agent chart and container images.
  2. Deploy BMC Helix Monitor Agent.
  3. Verify the BMC Helix Monitor Agent deployment.

The following sections explain the steps in detail.

Downloading the BMC Helix Monitor Agent chart and container images

  1. Log in to EPD  by using your Support user ID and password. You might also be prompted to complete the Export Compliance Form. If you are accessing this site for the first time, create a new EPD profile to specify the languages and platforms that you want to download. For assistance with EPD, see  EPD site help.

  2. Download the helix-monitor-agent-24.2.00.tar helm chart to a temporary directory.
  3. Download the container-token.bmc file that contains the Docker token.

Download link for the installation file

Contains of the downloaded file

Important

Download the token again even if you have downloaded it for an earlier release.

Container images

BMC containers images are distributed from https://containers.bmc.com. You can access the containers for the licensed products by using your registered support account and a new password. This password is saved in a file which is downloaded with this PDF file. The password is shared among all the containerized BMC software that you have access to.

Check your downloads directory for the container-token.bmc file that contains your generated password. For step-by-step instructions on how to use this password to obtain the BMC container images, see  Setting-up-a-Harbor-repository.

Deploying BMC Helix Monitor Agent

  1. Copy the downloaded helix-monitor-agent-24.2.00.tar file to the controller or bastion machine from where the Kubernetes and OpenShift cluster is accessible.
  2. Extract the tar file.

  3. Create image pull secret by using one of the following commands:  

    • For Kubernetes:

      kubectl create secret docker-registry <image pull secret name> --docker-server=containers.bmc.com --docker-username=<docker registry user name> --docker-password=<docker registry password> --docker-email=<docker registry email>

    • For OpenShift:

      oc create secret docker-registry <image pull secret name> --docker-server=containers.bmc.com --docker-username=<docker registry user name> --docker-password=<docker registry password> --docker-email=<docker registry email>

    Important

    For the local repository, ensure that you change the docker-server value in this command.

  4. There are three (3) helm charts available in the downloaded file. Extract the required file from the downloaded files by running the following command:

    tar -zxf <filename>

    The default yaml file is helix-monitor-agent/values.yaml. You must replace all values starting and ending with __.  Also, replace image pull secret name with the newly created secret name.

    Blank values.yaml file

    # Default values for helix-monitor-agent
    # This is a YAML-formatted file.
    # Declare variables to be passed into your templates.

    registryhost: __DOCKER_REPOSITORY_HOSTNAME__

    namespace: __NAMESPACE__
    imagePullSecrets:
      name: bmc-epdhub
      enabled: true

    image:
      repository: bmc/lp411
      pullPolicy: IfNotPresent
      tag: helix-monitor-agent-23.2.00-30

    service:
      name: patrolagent
      ports:
        port: 3181
        name: pa-port

    containers:
      secrets:
        apikey: __APIKEY__
        certificate: "__CERTIFICATE__"
      envMap:
        BHOM_TENANT_URL: __BHOM_TENANT_URL__
        PUBLISHOSTNAME: __HOSTNAME__
        TAGS: CNTR
        FORWARDPROXYSERVER: ""
        FORWARDPROXYUSER: ""
        FORWARDPROXYPASSWD: ""
      maxlogsize: 3Gi
      resources:
        limits:
          cpu: 500m
          memory: 4096Mi
        requests:
          cpu: 100m
          memory: 1024Mi

  5. Open the values.yaml file in a text editor and edit the following details:

    Yaml parameters

    Configuration

    Details

    registryhost

    The docker registry host containing the Helix Monitor Agent. The default value is containers.bmc.com.

    namespace

    Specify the namespace where you want to deploy the Helix Monitor Agent container. 

    imagePullSecrets

    Secret to authenticate with a container registry to pull an image. For more information, see Pull an Image from a Private Registry.

    name

    The name of Secrets. Replace image pull secret name with the newly created secret name.

    enabled

    Set it true when you want to enable imagePullSecrets.

    Image

    repository  

    The location on the registry where the container image exists. Modify the parameter if you are using a local repository.

    pullPolicy 

    Image pull policy for pod.

    Options available:

    • Always
    • IfNotPresent
    • Never

    tag (Optional)

    Container image tag. Modify the parameter only if you have created custom tags on containers.

    Service

    name

    The Kubernetes or OpenShift deployment name. This name must be unique in a namespace. 

    ports (Optional)

    The port used by PATROL Agent.

    API Key

    1. In BMC Helix Operations Management, navigate to Administration > Repository.

    2. Click Copy API key and paste it in the values.yaml file.
      If you have configured a rotation interval for the API key in BMC Helix Portal, make sure that you use the latest API key each time the key rotates. For instructions about configuring a rotation interval, see Using API keys for external integrations.

    BHOM tenant URL

    Enter https:< BMC Helix Operations Management tenant URL>:443.
    For example, https:example-hostname.bmc.com:443 .

    Certificate

    Chrome browser
    1. Click the lock sign before the BMC Helix Operations Management URL.
    2. Click Connection is secure and then click Certificate is valid.
    3. Click the Certificate Path tab.
    4. Select the root certificate path (for example, DigiCert Global Root CA) and then click View Certifiate.
    5. Click the Details tab and then click Copy to File.
    6. On the Certificate Export Wizard, click Next.
    7. On the Export File Format page, select Base 64 encoded X.509 (.CER) and then click Next.
    8. In the File Name field, enter the file name to save the certificate and browse a folder to save the file.
    9. Open the file where you saved the certificate and copy the certificate.
      Do not copy the BEGIN CERTIFICATE and END CERTIFICATE lines.
    10. Back in the configuration file, paste the certifiate enclosed in single quotes ('').
      The following image shows the process to download and copy the certificate:
      CopyingCertificateChrome.gif
    Firefox browser
    1. Click the lock sign before the BMC Helix Operations Management URL.
    2. Click Connect secure and then click More information.
    3. Click View Certificate.
    4. Click the root certificate tab (for example, DigiCert Global Root CA).
    5. In the Miscellaneous section, click PEM (cert) and save the file.
    6. Open the downloaded file and copy the certificaate.
      Do not copy the BEGIN CERTIFICATE and END CERTIFICATE lines.
    7. Back in the configuration file, paste the certifiate enclosed in single quotes ('').
      The following image shows the process to download and copy the certificate:
      CopyingCertificateFirefox.gif

    Publishhostname

    The hostname by which PATROL Agent is displayed in BMC Helix Operation Management. There should not be any other existing Agent with the same host name.

    Tags (Optional)

    Tags with which PATROL Agent identifies in the server.

    maxlogsize (optional)

    The maximum amount of ephemeral storage container consumes on Kubernetes or OpenShift for the logs folder.

    Resources  (Optional)

    Limits (CPU, memory)

    The upper limit of CPU and memory resources allotted for the container. For more information, see Resource Management.

    Requests (CPU, memory)

    The minimum CPU and memory resources allotted for the container. For more information, see Resource Management.

    Forward Proxy configuration

    If you have configured forward proxy server, enter the username, password, and the forward proxy URL.

    Multi-node specific Kubernetes or OpenShift variable

    enableNodeDeployment

    Set the variable to true.

    enableNodeFileSystemMonitoring

    Set the variable to true.

    enableNodeNetworkMonitoring

    Set the variable to true.

    Tags 

    Tags with which PATROL Agent identifies in the server. (Use tag name in agent selection criteria while creating monitor policy)

    BMC_VE3_KM_INCLUDE_CLUSTER_NAME

    1 => include cluster name and project name (Default)
    2 => include only cluster name
    0 => not include cluster name

    BMC_VE3_KM_ENVIRONMENT_NAME
    BMC_VE3_KM_CLUSTER_NAME

    When configuring a monitoring policy for multiple clusters, set the following variables if you don’t want to use values mentioned in monitoring policy. For example:

    BMC_VE3_KM_ENVIRONMENT_NAME: "bmc-env"
    BMC_VE3_KM_CLUSTER_NAME: "bmc-cluster"

    You have the option to either leave both values empty, which represents the default setting, or to specify both values. Using only one of these values is not allowed.

    Sample values.yaml file

    # Default values for helix-monitor-agent
    # This is a YAML-formatted file.
    # Declare variables to be passed into your templates.

    registryhost: test-harboreg.bmc.com

    namespace: patrolagent
    imagePullSecrets:
      name: bmc-epdhub
      enabled: true

    image:
      repository: bmc/lp411
      pullPolicy: IfNotPresent
      tag: helix-monitor-agent-23.2.00-30

    service:
      name: patrolagent
      ports:
        port: 3181
        name: pa-port

    containers:
      secrets:
        apikey: 1a11aa1a-1aa1-111a-1111-11a11a11111a
        certificate: "MIIDrzCCApegAwIBAgIQCDvgVpBCRrGhdWrJWZHHSjANBgkqhkiG9w0BAQUFADBh
    MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMRkwFwYDVQQLExB3
    d3cuZGlnaWNlcnQuY29tMSAwHgYDVQQDExdEaWdpQ2VydCBHbG9iYWwgUm9vdCBD
    QTAeFw0wNjExMTAwMDAwMDBaFw0zMTExMTAwMDAwMDBaMGExCzAJBgNVBAYTAlVT
    MRUwEwYDVQQKEwxEaWdpQ2VydCBJbmMxGTAXBgNVBAsTEHd3dy5kaWdpY2VydC5j
    b20xIDAeBgNVBAMTF0RpZ2lDZXJ0IEdsb2JhbCBSb290IENBMIIBIjANBgkqhkiG
    9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4jvhEXLeqKTTo1eqUKKPC3eQyaKl7hLOllsB
    CSDMAZOnTjC3U/dDxGkAV53ijSLdhwZAAIEJzs4bg7/fzTtxRuLWZscFs3YnFo97
    nh6Vfe63SKMI2tavegw5BmV/Sl0fvBf4q77uKNd0f3p4mVmFaG5cIzJLv07A6Fpt
    43C/dxC//AH2hdmoRBBYMql1GNXRor5H4idq9Joz+EkIYIvUX7Q6hL+hqkpMfT7P
    T19sdl6gSzeRntwi5m3OFBqOasv+zbMUZBfHWymeMr/y7vrTC0LUq7dBMtoM1O/4
    gdW7jVg/tRvoSSiicNoxBN33shbyTApOB6jtSj1etX+jkMOvJwIDAQABo2MwYTAO
    BgNVHQ8BAf8EBAMCAYYwDwYDVR0TAQH/BAUwAwEB/zAdBgNVHQ4EFgQUA95QNVbR
    TLtm8KPiGxvDl7I90VUwHwYDVR0jBBgwFoAUA95QNVbRTLtm8KPiGxvDl7I90VUw
    DQYJKoZIhvcNAQEFBQADggEBAMucN6pIExIK+t1EnE9SsPTfrgT1eXkIoyQY/Esr
    hMAtudXH/vTBH1jLuG2cenTnmCmrEbXjcKChzUyImZOMkXDiqw8cvpOp/2PV5Adg
    06O/nVsJ8dWO41P0jmP6P6fbtGbfYmbW0W5BjfIttep3Sp+dWOIrWcBAI+0tKIJF
    PnlUkiaY4IBIqDfv8NZ5YBberOgOzW6sRBc4L0na4UU+Krk2U886UAb3LujEV0ls
    YSEY1QSteDwsOoBrp+uvFRTp2InBuThs4pFsiv9kuXclVzDAGySj4dzp30d8tbQk
    CAUw7C29C79Fv1C5qfPrmAESrciIxpg0X40KPMbp1ZWVbd4="
      envMap:
        BHOM_TENANT_URL: https:testhost.bmc.com:443
        PUBLISHOSTNAME: oraclemonitor.bmc.com
        TAGS: CNTR
        FORWARDPROXYSERVER: ""
        FORWARDPROXYUSER: ""
        FORWARDPROXYPASSWD: ""
      maxlogsize: 3Gi
      resources:
        limits:
          cpu: 500m
          memory: 4096Mi
        requests:
          cpu: 100m
          memory: 1024Mi

  6. Run the following command: 

    helm3 install -f <override values yaml file path> <helm deplyoment name> <container file name>

    For example, helm3 install -f helix-monitor-agent/values.yaml k8s-agent helix-monitor-agent-24.2.00.tgz

    Sample deployment output

    NAME: abs-agent
    LAST DEPLOYED: Mon Mar 25 06:34:36 2024
    NAMESPACE: patroldev
    STATUS: deployed
    REVISION: 1
    TEST SUITE: None

Verifying the deployment

  1. Run the following command to check the helm chart deployment status:

    helm3 list
  2. In BMC Helix Operations Management, navigate to Configuration > Agents. 
  3. Search for BMC Helix Monitor Agent by entering its name in the search box.
    For a BMC Helix Monitor Agent, the version ends with letter c.

Container_1.JPG.png


To uninstall BMC Helix Monitor Agent

  1. Run the following command:
    helm3 uninstall <deployment name>

  1. To verify the uninstallation, run the following command:

    helm3 list


FAQs

What PATROL Agent features are not available in the containerized version?
  • Port 3181 is not exposed outside the container. Therefore, no PatrolCli or console connection is possible from the host computer or within the container.
  • You cannot change or re-configure the default account for the BMC Helix Monitor Agent.
  • KM push is not supported.
  • You cannot modify the container contents after deployment.
  • You cannot restart the Agent.
How to collect Agent debug logs?

To enable the BMC Helix Monitor Agent debug logs, go to Configuration > Agents and use the Query PATROL Agent option from the actions menu for the Agent.

If the Agent is not connected to BMC Helix Operations Management, start a new Agent process with debug flags in the container on a different port.

Copy the debug log files from the container manually. 

How to collect KM debug logs?

Enable the KM debug logs option in the KM configuration.

To copy the debug log files from the container manually:

  1. Use the following command to get pod’s name:

    kubectl get po | grep <service name defined in values.yml>

  2. Use the following command to copy the file from pod:

    kubectl cp <namespace>/<podname>:<LogFilePath>   <localFolderPath>
Can I push additional KMs to BMC Helix Monitor Agent?

No.

Can I upgrade KMs on BMC Helix Monitor Agent?

You cannot upgrade KMs by deploying a package. To upgrade a KM, upgrade BMC Helix Monitor Agent.  

How can I upgrade BMC Helix Monitor Agent?

Download the helm chart from the BMC EPD website and run the following command:

helm3 upgrade -f <override values yaml file path> <helm deplyoment name> <container file name>

What Java location shall I use in the Java Home or Java Path fields while configuring the KMs?

In a container, Java is installed at /opt/java. Set JAVA_HOME as /opt/java.

How to check PATROL Agent error logs from controller?

Run the following commands:

  1. To search the pod, run kubectl get po 
  2. Then run, kubectl logs <POD name>




 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*