The site that you are currently viewing is a static version of the Software Factory documentation delivered with the

version v7.2.
For up-to-date documentation, see the latest version.

Operations Guide

Document maturity: DRAFT

IMPORTANT NOTICE!

Starting with version 8.0.0, Synopsys Alert has been renamed Black Duck Alert. For legacy and structure reasons in the current document, any reference to Synopsys Alert product name can be used interchangeable with Black Duck Alert. Outside of this, any code block, reference to a value/parameter should be used “as is”.

Referenced documentation

Document referenceDocument Name
TASDTechnical Architecture and Security Document of SWaaP
LLD-BlackDuckAlertLow level design of Black Duck Alert component

Introduction

The Black Duck Alert component is part of Software Factory as a Package (SWaaP).

Black Duck Alert enables you to see the Black Duck notifications you want, where and when you want them. Alert supports a number of commonly used distribution channels, such as email, Slack, Azure Boards, and Jira. Alert streamlines the process of getting timely, valuable Black Duck related notifications to key stakeholders. Alert is an independent web application that runs on its own with its own user interface. Once configured, it runs continuously in the background receiving notifications from Black Duck and delivering those notifications to configured recipients using the configured channels. Administrators can verify the successful sending of notifications through the Alert Audit screen.

Learn more about it in LLD-BlackDuckAlert and in TASD .

Billing and Onboarding

Black Duck Alert is part of the Advanced Software Composition Analysis (SCA) offer together with Black Duck SCA.

Billing & Onboarding on TDP

The Advanced Software Composition Analysis (SCA) offer is not available yet.

Billing & Onboarding on RTDP

The Advanced Software Composition Analysis (SCA) offer is not available yet.

Billing & Onboarding on CASTLE

The Advanced Software Composition Analysis (SCA) offer is not available yet.

Component Deployment and Configuration

Requirements & Pre-requisite

See LLD-BlackDuckAlert §4.2 prerequisites & Limitations

Configuration

Setting Helm Values

Black Duck Alert component is part of SWaaP. For more information, refer to the Mandatory Black Duck Alert values section in the reference repository.

Configuring Kubernetes Secrets

Configuring Kubernetes secrets - Black Duck Alert

Note that, based on the [Helm] values you provide, additional Kubernetes secrets and configmaps may also be required.

Deployment & Update Procedure

Black Duck Alert deployments and upgrades are automated using Flux, a GitOps framework.

Here’s an example of a Release YAML file used for deployment and upgrade.

apiVersion: helm.toolkit.fluxcd.io/v2beta1
kind: HelmRelease
metadata:
  name: synopsys-alert
spec:
  releaseName: synopsys-alert
  chart:
    spec:
      chart: blackduck-alert
      version: 8.0.0
      sourceRef:
        kind: HelmRepository
        name: synopsys-alert
  install:
    crds: Skip
  upgrade:
    crds: Skip
  interval: 10m
  timeout: 20m

  valuesFrom:
    # Default values of the chart. Shall not be modified.
    - kind: ConfigMap
      name: helm-common-values
      valuesKey: swf-chart-default-values.yaml
    # All overrides are here (if not in a more specialized files below)
    - kind: ConfigMap
      name: helm-common-values
      valuesKey: swf-overrides-default-all.yaml
    # Overrides related to the usage of a private registry
    - kind: ConfigMap
      name: helm-images-values
      valuesKey: swf-overrides-var-images.yaml
    # These platform specific Values shall always exist. Even empty.
    - kind: ConfigMap
      name: helm-sizing-values
      valuesKey: sizing.yaml
    - kind: ConfigMap
      name: helm-platform-values
      valuesKey: platform.yaml
    - kind: Secret
      name: alertencryption
      valuesKey: password
      targetPath: alertEncryptionPassword
      optional: true
    - kind: Secret
      name: alertencryption
      valuesKey: password
      targetPath: secretEnvirons.ALERT_ENCRYPTION_PASSWORD
      optional: true
    - kind: Secret
      name: alertencryption
      valuesKey: salt
      targetPath: alertEncryptionGlobalSalt
      optional: true
    - kind: Secret
      name: alertencryption
      valuesKey: salt
      targetPath: secretEnvirons.ALERT_ENCRYPTION_GLOBAL_SALT
      optional: true
  postRenderers:
    - kustomize:
        patches:
          - target:
              kind: Deployment
            patch: |
              - op: add
                path: /metadata/annotations/linkerd.io~1inject
                value: disabled
              - op: add
                path: /spec/template/metadata/annotations/linkerd.io~1inject
                value: disabled
apiVersion: source.toolkit.fluxcd.io/v1beta2
kind: HelmRepository
metadata:
  name: synopsys-alert
spec:
  interval: 30m
  url: ${helmRepositoryUrl:="https://repo.blackduck.com/sig-cloudnative"}

Note:
Before any upgrade please back up existing data (DB, Storage, etc)

Official docs for deployment and upgrade:

IMPORTANT NOTICE! (when upgrading to Blackduck Alert 8.0.0 )

  • ⚠ Synopsys Alert has been renamed Black Duck Alert and also the helmchart name was renamed from synopsys-alert to blackduck-alert.

    • This doesn’t generate any impact for regular Helm upgrades.
    • For Flux upgrades, this will cause an uninstall of the current version (installed from synopsys-alert helmchart) and an actual install (instead of upgrade) with the new “blackduck-alert” helmchart, resulting in PV/PVCs recreation. Checked the scenario and this has no real impact on the platform as there are no critical files affected. More on this in the documentation
  • ⚠ A new flag postgres.sslMode has been added when using an external DB with helm .

    • The default ssl mode is now set as ‘disable’ throughout the deployment files.
    • With SSL enabled, if postgres.sslUseFiles is true, Alert will now individually verify the settings; postgres.sslSecrets, postgres.sslSecrets.sslKeyKey, postgres.sslSecrets sslCertKey, and postgres.sslSecrets.sslRootCertKey. For any flags set, the deployment will add the secret to the pod.
    • The docker-entrypoint script for Alert will now dynamically configure the DB connection string for sslkey, sslcert, and sslrootcert. If the script finds the value to be set, it will include it in the connection string otherwise it will not be included.
    • postgres.sslKeyKey and postgres.sslCertKey values must both be specified. Configuring just one or the other is invalid, and they will be ignored when Alert starts.

Settings

PostgreSQL configuration YAML file, e.g. pg.yaml Postgress configuration

The exposed parameter postgres.claimSize only applies to Postgress instance deployed by alert (not external).

ParameterDescriptionDefault
postgres.claimSizePostgres node volume claim size"5Gi"

The persistance size for Postgress service is set in pg.yaml

primary:
  persistence:
    size: 10Gi

Black Duck Alert platform setup, installation and deployment YAML file, e.g. platform.yaml Black Duck Alert configuration

Sizing configuration file for components in Black Duck Alert deployment, e.g. sizing.yaml

ParameterDescriptionDefault
alert.resources.limits.memoryAlert container Memory Limit2560M
alert.resources.requests.memoryAlert container Memory Request2560M
alert.claimSizeThe persistent storage claim size limit5Gi
rabbitmq.claimSizeRabbitMQ node volume claim size"2Gi"
rabbitmq.resources.limits.memoryRabbitMQ node memory limit"1024Mi"

Currently in SWaaP, Black Duck Alert is configured with enableStandalone set to false meaning Alert uses the cfssl pod from blackduck’s namespace. The below limits for the cfssl pod are only relevant if enableStandalone is set to true.

ParameterDescriptionDefault
enableStandaloneIf true, Alert will be deployed with it’s own cfssl instancetrue
cfssl.resources.limits.memoryCfssl container Memory Limit640M
cfssl.resources.requests.memoryCfssl container Request Limit640M

Note: Please note that the values are placeholders and can be customized as per your requirements.

For the full list of Black Duck Alert configurable paramentes check out Black Duck Alert Helm Chart Configuration

Once Alert is installed you will need to configure it. Some configurations like encryption and certificates are handled on install. Both can also be configured from the web UI, should the need arise for a new integration (e.g. for adding a JIRA certificate)

Functional Configuration

Depending on what you want to use, you will need to configure providers (BlackDuck), the channels to use for notifications and scheduling.

General configuration: Configuring Black Duck Alert

Configure how Alert sends notifications:

Black Duck does not specify an autoscaling strategy for Alert. Since Alert does not use too many resources we recommend increasing the resources for the deployed pods if the need arrises (high CPU, high memory consumption).

Monitoring

Black Duck Alert is deployed with a Swagger documentation endpoint. In order to access the swagger endpoint go to the alert web UI and select on Help then on REST API Developers Guide. This will take you to the Swagger API documentation of Alert. Open Swagger

Alert provides a diagnostics endpoint that returns relevant system and business metrics. The diagnostics endpoint is hosted at synopsys-alert-url/api/diagnostic. Performing a GETrequest with no parameters will return a dictionary in JSON format, containing diagnostic data objects with the diagnostic values.

Example request using curl:

curl -X 'GET' \
  'https://alert_url/api/diagnostic' \
  -H 'accept: */*'

Example diagnostics response:

{
  "notificationDiagnosticModel": {
    "numberOfNotifications": 0,
    "numberOfNotificationsProcessed": 0,
    "numberOfNotificationsUnprocessed": 0,
    "providerNotificationCounts": [
      {
        "providerConfigId": 0,
        "notificationCounts": [
          {
            "notificationType": "BOM_EDIT",
            "count": 0
          }
        ]
      }
    ]
  },
  "auditDiagnosticModel": {
    "numberOfAuditEntriesSuccessful": 0,
    "numberOfAuditEntriesFailed": 0,
    "numberOfAuditEntriesPending": 0,
    "averageAuditTime": "string"
  },
  "systemDiagnosticModel": {
    "availableProcessors": 0,
    "maxMemory": 0,
    "totalMemory": 0,
    "freeMemory": 0,
    "usedMemory": 0
  },
  "rabbitMQDiagnosticModel": {
    "queues": [
      {
        "name": "string",
        "messageCount": 0,
        "consumerCount": 0
      }
    ]
  },
  "completedJobsDiagnosticModel": {
    "completedJobs": [
      {
        "jobConfigId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "jobName": "string",
        "latestNotificationCount": 0,
        "totalNotificationCount": 0,
        "successCount": 0,
        "failureCount": 0,
        "latestStatus": "string",
        "lastRun": "string",
        "durations": {
          "jobDuration": "string",
          "stageDurations": [
            {
              "name": "string",
              "duration": "string"
            }
          ]
        }
      }
    ]
  },
  "jobExecutionsDiagnosticModel": {
    "totalJobsInSystem": 0,
    "pendingJobs": 0,
    "successFulJobs": 0,
    "failedJobs": 0,
    "jobExecutions": [
      {
        "jobName": "string",
        "channelName": "string",
        "start": "string",
        "end": "string",
        "status": "PENDING",
        "processedNotificationCount": 0,
        "totalNotificationCount": 0,
        "remainingEvents": 0,
        "stages": [
          {
            "stage": "NOTIFICATION_PROCESSING",
            "start": "string",
            "end": "string"
          }
        ]
      }
    ]
  },
  "requestTimestamp": "string"
}

For a complete definition of the schemas for the Diagnostic Model objects check out Alert Swagger.

System health metrics

SystemDiagnosticModel{
  availableProcessors integer($int32)
  maxMemory integer($int64)
  totalMemory integer($int64)
  freeMemory  integer($int64)
  usedMemory  integer($int64)
}
RabbitMQDiagnosticModel{
  queues  [AlertQueueInformation{
    name  string
    messageCount  integer($int32)
    consumerCount integer($int32)
  }]
}
AlertQueueInformation{
  name  string
  messageCount  integer($int32)
  consumerCount integer($int32)
}

Business Metrics

Schema of the response from diagnostics endpoint, containing bussiness metrics:

DiagnosticModel {
    notificationDiagnosticModel NotificationDiagnosticModel {
        numberOfNotifications integer($int64)
        numberOfNotificationsProcessed integer($int64)
        numberOfNotificationsUnprocessed integer($int64)
        providerNotificationCounts[ProviderNotificationCounts {
            providerConfigId integer($int64)
            notificationCounts[NotificationTypeCount {
                notificationType string
                  Enum: [BOM_EDIT, COMPONENT_UNKNOWN_VERSION, LICENSE_LIMIT, POLICY_OVERRIDE, PROJECT, PROJECT_VERSION, RULE_VIOLATION, RULE_VIOLATION_CLEARED, VERSION_BOM_CODE_LOCATION_BOM_COMPUTED, VULNERABILITY]
                count integer($int64)
            }]
        }]
    }
    auditDiagnosticModel AuditDiagnosticModel {
        numberOfAuditEntriesSuccessful integer($int64)
        numberOfAuditEntriesFailed integer($int64)
        numberOfAuditEntriesPending integer($int64)
        averageAuditTime string
    }
    systemDiagnosticModel SystemDiagnosticModel {
        availableProcessors integer($int32)
        maxMemory integer($int64)
        totalMemory integer($int64)
        freeMemory integer($int64)
        usedMemory integer($int64)
    }
    rabbitMQDiagnosticModel RabbitMQDiagnosticModel {
        queues[AlertQueueInformation {
            name string
            messageCount integer($int32)
            consumerCount integer($int32)
        }]
    }
    completedJobsDiagnosticModel CompletedJobsDiagnosticModel {
        completedJobs[CompletedJobDiagnosticModel {
            jobConfigId string($uuid)
            jobName string
            latestNotificationCount integer($int64)
            totalNotificationCount integer($int64)
            successCount integer($int64)
            failureCount integer($int64)
            latestStatus string
            lastRun string
            durations CompletedJobDurationDiagnosticModel {
                jobDuration string
                stageDurations[CompletedJobStageDurationModel {
                    name string
                    duration string
                }]
            }
        }]
    }
    jobExecutionsDiagnosticModel JobExecutionsDiagnosticModel {
        totalJobsInSystem integer($int64)
        pendingJobs integer($int64)
        successFulJobs integer($int64)
        failedJobs integer($int64)
        jobExecutions[JobExecutionDiagnosticModel {
            jobName string
            channelName string
            start string
            end string
            status string
              Enum: [PENDING, SUCCESS, FAILURE]
            processedNotificationCount integer($int32)
            totalNotificationCount integer($int32)
            remainingEvents integer($int32)
            stages[JobStageDiagnosticModel {
                stage string
                  Enum: [NOTIFICATION_PROCESSING, CHANNEL_PROCESSING, ISSUE_CREATION, ISSUE_COMMENTING, ISSUE_TRANSITION]
                start string
                end string
            }]
        }]
    }
    requestTimestamp string
}