Skip to content

_Black Duck Installation Parameters

Jump to bottom
Jonathan Beakley edited this page Jun 10, 2019 · 1 revision

This page has been deprecated. Please see the official Kubernetes Black Duck Installation Guide here.

Introduction

When using Synopsys Operator to install a Black Duck instance, there are many parameters that can be provided to customize the installation.

This page lists the parameters by task, and gives instructions for configuring them from the Console UI and the command line.

The following tasks are covered:

Note: There are some Black Duck configurations that can only be made manually (and not with Synopsys Operator). See Other Black Duck Configuration for details.

Black Duck Registration Key

No matter whether you install Black Duck from the command line or with the console UI, you must provide a Black Duck license key; otherwise, the registration portion of the deployment will fail. In the console UI, provide the key in the "License Key" field. From the command line, provide the key in the "licenseKey" field.

Black Duck Namespace

You can configure the name of the namespace you want to install Black Duck in. Generally, you want each Black Duck instance to be in its own namespace.

In the Console UI, provide the namespace in the "Namespace" field.

In the sample JSON files, change the "namespace" field. Note: It is recommended that you change the "name" field (in the metadata) to match the namespace field.

Black Duck Size

You can specify how many resources in the cluster will be allocated to the Black Duck instance. The option you pick affects:

  • Number of CPU cores
  • Amount of Memory
  • The number of replicas of certain Black Duck containers (JobRunner, Black Duck Scan, etc.)
  • The maximum number of concurrent scans

The table below specifies what is allocated for a Black Duck deployment of a given size:

|Size    |CPU Cores |Memory |Num JobRunners |Num Scans |
+--------+----------+-------+---------------+----------+
|Small   |8         |32G    |1              |1         |
|Medium  |12        |64G    |4              |2         |
|Large   |14        |144G   |6              |3         |
|X-Large |20        |224G   |10             |5         |

In the Console UI, the "Size" field can be set to "Small", "Medium", "Large", and "X-Large". The same values can be set in the sample JSON file in the "size" field. Pick the size that matches your cluster's resources.

Black Duck Type

This field is used for the OpsSight Connector only. This field should remain blank if you do not use the OpsSight Connector.

This field is used to indicate whether you want this Black Duck instance to be send scan data by the OpsSight Connector. By default, the OpsSight Connector will send scan data to all Black Duck instances that:

  1. exist in the cluster
  2. were installed using Synopsys Operator
  3. have a "type" value that exactly matches that of the OpsSight Connector

If you would like this Black Duck instance to receive OpsSight Connector scan data, ensure that this "type" value matches the value that was set when the OpsSight Connector is installed. (The default value for the OpsSight Connector is "worker".)

Persistent Storage

Synopsys Operator can create persistent volume claims that will ensure that Black Duck's data persists even if its containers are stopped and restarted. For a full discussion of this complex topic, see the Persistent Volume Considerations page.

To enable use of persistent volumes by Black Duck, check the "Persistent Storage" checkbox in the Synopsys Operator Console UI. If editing the example JSON files, set "persistentStorage: true".

If Persistent Storage is enabled, you must also provide the following values:

"PVC Storage Class" / "pvcStorageClass"

If you have multiple classes (types) of persistent volumes defined in your cluster, you can specify the class of storage for the volume that is claimed by Black Duck. In the Synopsys Operator Console UI, the "PVC Storage Class" drop-down selector will be populated with the storage classes defined in your cluster, and you can simply select one. If using JSON files, the "pvcStorageClass" value must be set to the exact name of the storage class. To see the names of defined storage classes, use the command:

kubectl get storageclass

"Scan Type" / "scanType"

This field exists solely to help populate the Postgres Claim Size (described below) in the Console UI. If you are using the Console UI, then:

  • If you are using OpsSight to scan containers, then select "Images". This will request a large database.
  • If you are scanning source code, then select "Artifacts". This will request a smaller database.
  • Select "Custom" if you intend to fill out the size manually, above. If you are editing the JSON file, you can ignore this field.

"Postgres Claim Size" / "size"

You must state how much storage will be requested by Black Duck's Postgres instance from the cluster's underlying persistent storage class. If you are using the Console UI, this field will be auto-populated for you based on the "Scan Type" (see above). If you are editing the JSON file, specify "150Gi" if you are scanning source files, and "1000Gi" if you are using OpsSight to scan images. Consult your authorized Synopsys support representative for guidance on database sizing. In the JSON file, create a stanza with the following form:

"pvc": [
            {
                "name": "blackduck-postgres",
                "size": "150Gi"
            }
        ],

Please note that the name of the PVC must be "blackduck-postgres".

(Note: Much more information on database configuration can be found on the Database Considerations page.)

External Database

You can configure your Black Duck deployment to use an external database.

Important note: Before you can use this option, you must properly configure the external database. For instructions, please reference the section entitled "Configuring an external PostgreSQL instance" in the Black Duck Compose installation documentation, which can be found here.

Once you have properly configured the external database, you must supply the following parameters appropriately:

"External Database" / "externalPostgres"

If using the Console UI, check the "External Database" checkbox. If using a JSON file, ensure that you have an appropriate "externalPostgres" stanza (see the "hub_external_database.json" example file for an example).

"PostgreSQL Host" / "postgresHost"

This is the IP Address (or hostname) of the external database.

"PostgreSQL Port" / "postgresPort"

This is the port of the external database.

"PostgreSQL Admin User" / "postgresAdmin"

This is the admin user id of the external database. (This is usually "blackduck".)

"PostgreSQL User" / "postgresUser"

This is the user id of the external database that Black Duck uses to access the database. (This is usually "blackduck_user".)

"Enable SSL" / "postgresSsl"

Check this checkbox (or set the JSON value to true) if the database connection uses SSL.

"PostgreSQL Admin Password" / "postgresAdminPassword"

Password for the admin user. This information is put in a Kubernetes secret.

"PostgreSQL User Password" / "postgresUserPassword"

Password for the regular DB user. This information is put in a Kubernetes secret.

(Note: Much more information on external databases can be found on the Database Considerations page.)

Cloning a Database

If you have a pre-existing Black Duck instance in your cluster that was deployed with Synopsys Operator, then you can clone that instance's database and use it to populate the new Black Duck instance.

In the Console UI, the "Clone DB" drop-down provides a list of Black Duck instances. Select a Black Duck instance from this list to clone its database, or choose "None" to start with a fresh database. If using a JSON file from the command line, you can provide the Black Duck name in the "dbPrototype" field (having no "dbPrototype" entry in the JSON file will cause a fresh database to be created).

Web Server Certificates

Each Black Duck web UI responds to HTTPS requests, and therefore, needs a certificate for authentication. You can either have Synopsys Operator create a self-signed certificate for you, or, you can provide a certificate of your own. In either case, the certificate will be made available to the Black Duck server via a Kubernetes secret.

To choose a self-signed cert, choose "default" in the "Certificate Name" field of the Console UI. In the JSON file, set the "certificateName" field to "default".

If you would like to provide your own custom certificate, set the value to "manual" rather than "default". In this case, you must specify two other field values:

"Certificate" / "certificate"

In this field, place all the base64-encoded X.509 certificate information for your custom cert. (Get this from your PEM file. You can include the "----- Begin" and "----- End" comments.)

Certificate Key

In this field, place all base64-encoded private key of your custom cert. (Get this from your PEM file. You can include the "----- Begin" and "----- End" comments.) If using the JSON file, you may wish to delete the JSON file after deploying Black Duck to avoid compromising the private key.

Custom Certificate Authority for Client Authentication

Each Black Duck instance provides an API that can be accessed by a client via a TLS connection. Each client must authenticate with the Black Duck instance, and one supported form of authentication is certificate auth. When the client passes the certificate to the server during the TLS handshake, the server must verify that the client certificate itself was signed by a trusted authority. You can provide a certificate for the trusted authority so the server will trust your clients. To provide a custom certificate-authority certificate, provide the certificate details under the "Custom CA for certificate authentication" field in the console UI, or the "authCustomCa" field in a JSON file. The value should be base64 encoded, for example:

authCustomCa: |
    -----BEGIN CERTIFICATE-----
    MIIE1DCCArwCCQCuw9TgaoBKVDANBgkqhkiG9w0BAQsFADAsMQswCQYDVQQGEwJV
    UzELMAkGA1UECgwCYmQxEDAOBgNVBAMMB1JPT1QgQ0EwHhcNMTkwMjA2MDAzMjM3
    ...
    o1UGNrGgU1rK8K+/2htOH9JhlPFWHQkk+wvGL6fFI7p+6TGes0KILN4WioOEKY0t
    0V1Zr8bejDW49cu1Awy443SrauhFLOInubZLA8S9ZvwTVIvpmTDjdQ==
    -----END CERTIFICATE-----

Note: The CN field of the client certificate must match an existing user name.

Changing Web Server Ports and Hosts

By default, Black Duck's web server is publicly available on localhost port 443, and internal communication is through port 8443. Keeping the defaults is recommended, but they can be changed via Environment Variables.

If using the Console UI, then edit the "PUBLIC_HUB_WEBSERVER_HOST", "PUBLIC_HUB_WEBSERVER_PORT", and "HUB_WEBSERVER_PORT" to the values of your choice.

If editing a JSON file, make sure your "spec" stanza has text of the form:

    "environs": [
      "PUBLIC_HUB_WEBSERVER_HOST:localhost",
      "PUBLIC_HUB_WEBSERVER_PORT:443",
      "HUB_WEBSERVER_PORT:8443"
    ],

Disabling IPv6

Black Duck expects IPv6 to be enabled in order to function properly. If you want to install a Black Duck instance in a cluster that has IPv6 disabled, then two environment variables must be set.

If using the Console UI, then:

  1. Edit "IPV4_ONLY" and set the value to "1".
  2. Add a "BLACKDUCK_HUB_SERVER_ADDRESS" variable and set the value to "0.0.0.0".

If editing a JSON file, make sure your "spec" stanza has text of the form:

    "environs": [
      "IPV4_ONLY:1",
      "BLACKDUCK_HUB_SERVER_ADDRESS:0.0.0.0"
    ],

Enabling a Proxy

If you need to configure Black Duck to work with external proxies (i.e., you need to access Black Duck's registration or Knowledge Base services on the external Internet), then work with your proxy server administrator to help set the environment variables discussed, below.

If using the Console UI, then add the following three Environment Variables:

  • "HUB_PROXY_SCHEME"
  • "HUB_PROXY_HOST"
  • "HUB_PROXY_PORT" with the values of your choice.

If editing a JSON file, make sure your "spec" stanza has text of the form:

    "environs": [
      "HUB_PROXY_SCHEME:https",
      "HUB_PROXY_HOST:proxy.my.company",
      "HUB_PROXY_PORT:8080"
    ],

Liveness Probes

You can configure Synopsys Operator to enable liveness probes, which are like a health check. If enabled, Kubernetes/OpenShift itself will be configured to verify that all Black Duck containers are running properly and will restart them if they fail. (By default, Kubernetes will detect when a container or pod has exited (and attempt to restart the container in that case), but these Liveness Probes actually detect whether the application running inside each container is healthy, and will restart it if not.)

By default, Liveness Probes are disabled. To enable the Liveness Probes, either check the "Liveness Probes" checkbox in the Console UI, or if using a JSON file, set "livenessProbes" to "true".

Installing from a Different Registry

By default, Synopsys Operator will pull images from Docker Hub. If you wish to pull images from a secure registry you must first put the Black Duck images in that registry. For instructions, see Pushing Black Duck Images to a Secure Registry.

Once the Black Duck images are in the secure registry, you must do several things, listed below.

Creating an Image Pull Secret

See the Creating an Image Pull Secret page for guidance creating an image pull secret, which will store the credentials needed to access the secure registry.

Edit Image Tags

Now that you have the Black Duck images in the secure registry and have created the image pull secret, you can now edit the images tags to point to that registry.

If using the Console UI, go to the Container Image Tags section, and edit the values, adhering to the following format:

<registry>/<project>/<image-name>:<version>

For example, you might change:

blackducksoftware/blackduck-cfssl:1.0.0

to

registry.connect.redhat.com/blackducksoftware/blackduck-cfssl:1.0.0

Changing the Black Duck Version

If you wish to either:

  • install a version of Black Duck different from the defaults in the console UI / JSON files, or,
  • upgrade a Black Duck server to a new version

then you must do two things:

  1. edit the HUB_VERSION environment variable
  2. edit the Image Tags

Note: Before modifying these values, please contact Black Duck support to get the proper version value for each and every Black Duck container.

Changing the HUB_VERSION environment variable

This variable is used by the Black Duck instances to know what version it is and which version of the scan client to use.

If using the Console UI, then edit the "HUB_VERSION" variable as desired.

If editing a JSON file, make sure your "spec" stanza has text of the form:

    "environs": [
      "HUB_VERSION:2018.11.0"
    ],

Changing the Image Tags

If using the Console UI, modify each Container Image Tag value to match the version you wish to install. If editing a JSON file, edit the values appropriately in the "imageRegistries" stanza.

Black Duck Binary Analysis

To enable Black Duck Binary Analysis (BDBA), there are two steps:

  1. Ensure that the "USE_BINARY_UPLOADS" environment variable is set to "1"
  2. Ensure that you include the "appcheck-worker", "rabbitmq" and "blackduck-upload-cache" images tags. Instructions for each step is provided below.

Setting the Environment Variable

If using the Console UI, then ensure that the following line appears in the Environment Variables list:

"USE_BINARY_UPLOADS:1"

If editing a JSON file, make sure your "spec" stanza has text of the form:

    "environs": [
      "USE_BINARY_UPLOADS:1"
    ],

Installing the images

If using the Console UI, ensure that you specify the following Container Images Tags:

docker.io/blackducksoftware/appcheck-worker:1.0.1
docker.io/blackducksoftware/rabbitmq:1.0.0
docker.io/blackducksoftware/blackduck-upload-cache:1.0.3

If editing a JSON file, make sure your "spec" stanza has text of the form:

    "imageRegistries": [
      "docker.io/blackducksoftware/appcheck-worker:1.0.1",
      "docker.io/blackducksoftware/rabbitmq:1.0.0",
      "docker.io/blackducksoftware/blackduck-upload-cache:1.0.3"
    ],

Other Black Duck Configuration

There are some Black Duck configurations that can only be made manually (and not with Synopsys Operator). These configurations include persistent volumes for Postgres, and using an external database. To learn how to install Black Duck without using Operator, see Installing Black Duck in Clusters not Running the Operator.

Introduction

Troubleshooting

Deprecated

Clone this wiki locally