Installing on OpenShift using Helm charts

You can install HCL DevOps Velocity (Velocity) on OpenShift using Helm charts.

Before you begin

The tools required by all installation scenarios include the following items:
  • Docker installed on the host system.
    Note: If you use Docker for Windows, make sure Docker is using Linux-type containers. Velocity does not support Windows-type containers.
  • Internet connection. During installation, files and container images are retrieved from remote locations. If you are unable to access the internet during installation, you can download the files beforehand and perform an offline installation. Velocity supports the following browsers: Chrome, Firefox, and Edge.
    Note: These steps are only required if users are using the online installer to push images to an offline docker registry:

    Use pull command to pull the container images from public repository.

    $ docker pull public repo

    Use tag command to tag the public and private repository.

    $ docker tag public repo private repo

    Use push command to push container images to private repository.

    $ docker push private repo

    All the container images are retrieved from public to private repository.

Note: The installation files used for offline installation are not the same as those used for internet-connected installation. Ensure that you download the right file for your installation environment.

In addition to the requirements for all installation scenarios, you need the following items:

  • Configured OpenShift client instance. This topic uses Minishift for local instance installations.
  • OpenShift command line tool, OC, installed on the client.
  • Create an OpenShift project where you can install Velocity.
  • Access to the PEM-format certificate and private key that you can use to configure OpenShift routes.
  • Create new velocity-image-secret if required.
  • Master node: 2 vCPU, 8 GB RAM, 30 GB storage.
  • Other nodes: 1vCPU, 8 GB RAM, 15 GB storage.

About this task

The product installation requires an existing MongoDB database for data persistence. With the database, running the Velocity installer produces a Helm chart that is applied to the Kubernetes environment and instantiate the Kubernetes resources that comprise Velocity.

Additionally, you can configure an SSL certificate. If required, you can use Ingress instead of a Route.

To modify default parameters, installation options are configured with the --set name=value Helm syntax when creating the Helm release. Optionally, the values.yaml file is edited on the extracted Helm chart. Some options are not exposed as Helm values and must be modified on the Kubernetes resources either by modifying the extracted Helm chart templates, or patching them after the Helm release is created. For example, to configure the ephemeral Argo pods for running integrations, you modify the workflow-controller-configmap ConfigMap in the .../templates/configmap-workflow-controller.yaml file.

Note: To avoid Windows UAC permission issues, use PowerShell as administrator.
Note: The user who runs Helm installation command requires cluster-level permissions to create CustomResourceDefinitions. If you do not have access, consult your OpenShift administrator.

Procedure

  1. If you do not have a MongoDB database installed, install one now. Follow the instructions at the MongoDB GitHub repository.
    Sample commands for installing the MongoDB as follows:
    
         helm install velocity-mongo
         --set containerSecurityContext.runAsUser=PUID, podSecurityContext.fsGroup=PUID,auth.rootPassword=password,
         --set image.tag=<mongodb_version_number> bitnami/mongodb
    Note: To get PUID (Persistent), run oc describe project command with the project name.

    For example, to get PUID of the project helm-again, run oc describe project helm-again. The variable uid-range displays the PUID of the project.

    Note: If Helm cannot find the chart, try running the following command: helm repo add bitnami https://charts.bitnami.com/bitnami. If your organization uses a different repository, substitute it for bitnami/mongodb.
    To verify the installation, you can use the following commands:

    helm list

    helm status velocity-mongo

    To list all pods in the namespace, use the following command:

    kubectl get pods

    After the installation of MongoDB, use the below command to get the encrypted password

    kubectl get secrets velocity-mongo-mongodb -o yaml

    Search for the field mongodb-root-password: in encrypted password.

    Use the command echo -n "mongodb-root-password-value" | base64 --decode to decrypt the encrypted password.

    Use decrypted password to connect the application.

  2. Run the downloaded executable file.
  3. Run the installation script and respond to the prompts as described in the following steps.
    When the script starts, you are prompted to accept the license. You can explicitly accept the license without viewing it by appending the following parameter to the command:
    ./<velocity-installation-file> --license=accept
    1. At the Please enter your DevOps Velocity access key prompt, enter your SE version access key.
      If you previously installed an SE version, the already-configured key is the default value.
      Note: Make sure that you enter the key for the right version.
    2. At the Enter your encryption key or leave blank to use the default. Key must be at least 8 characters prompt, enter your encryption key or leave blank to use the default encryption key.
      Note: The encryption key must be at least 8 characters. Save the encryption key to use for further upgrades.
    3. At the Choose the platform prompt, select Helm.
    4. At the Enter the location where the DevOps Velocity files will be installed prompt, enter the location where you want to install the product files.
      Files are copied to the specified directory in a subdirectory named product_version_number.
    5. At the What version of MongoDB are you using? prompt, select the version of the MongoDB that you want to use for Velocity installation.
    6. At the Enter the initial password for the admin user prompt, enter your admin password.
    7. At the Please enter the hostname where you will run DevOps Velocity prompt, enter the host name where users can access the Web UI.
      The host name must resolve to a name on your DNS server, or in the server's hosts file. On Linux, the file location is etc/hosts; on Windows, the location is C:\Windows\System32\drivers\etc\hosts.
      Note: You cannot use localhost as the hostname. If you do not have any host names defined, for testing purposes you can use 127.0.0.1.nip.io. This location will redirect back to 127.0.0.1, which is typically used by localhost.
  4. To login, perform the following procedure:
    1. Click Copy Login Command from the drop-down list underneath the username to get token. Then, the page displays with Display Token link.
    2. Click Display Token to display the token.
    3. Copy oc login --token=sha256...... and run it in command prompt.
    4. Run oc projects to get list of all projects.
      Note: The oc projects displays all projects with the current project in last row of command result.
      Note: To change the project, enter the project name with oc projects command. For example, to access helm-again project, use oc projects helm-again.
  5. Note: If you are installing Velocity in an Amazon elastic Kubernetes service cluster, change the version of Kubernetes from kubeVersion:'>=1.11.0' to kubeVersion:'>=1.11.0-r0' in chart.yml file.
    Determine the configuration properties you can set for the helm install command with: helm show values /my\_installation/version\_number/accelerate-version.tgz
    The following code fragment displays a typical command:
    
         helm install velocity \
         ./accelerate-<version>-helm.tgz \
         --set runAsUser=PUID \
         --set license=accept \
         --set access.key=my_access_key \
         --set url.domain=my_hostname \
         --set mongo.url=mongodb://root:password@velocity-mongo-mongodb:27017
        
    Note: To get PUID (Persistent), run oc describe project command with the project name.

    For example, to get PUID of the project helm-again, run oc describe project helm-again. The variable uid-range displays the PUID of the project.

    Note: The unique name uc-velocity identifies the installed Helm release.

    Properties depend on your environment. The following properties are required. The optional properties are given later.

    access.key
    The product access key obtained earlier.
    runAsUser
    The PUID (Persistent Unique Identifier) obtained using oc describe project command.
    url.domain
    The hostname of your node or the Ingress host name.
    Note: This must match the hostname specified in the installer.
    mongo.url
    The URL of the MongoDB. Specify the following parameters.
    username
    The user ID to authenticate with the MongoDB database. For example, mongo.
    password
    The associated password to authenticate with the MongoDB database. For example, mongo.
    authSource
    If you connect to an authenticated MongoDB database, you can use authSource to specify the database where authenticated users are defined. For example, if the admin user is defined in the admin database, you can use mongodb://root:password@velocity-mongo-mongodb?authSource=admin.
    port
    The port number for the MongoDB database. Use the value shown in the example, which is 27017.
    service_name
    The MongoDB URL or the MongoDB service name if it is running within the Kubernetes cluster. For example, velocity-mongo-mongodb.
    database_name
    The name of the database to be used by Velocity. For example, velocity.
    Note: If you used the install command in the previous step to install the MongoDB, use the following values for the mongo.url property.
    --set mongo.url=mongodb://mongo:mongo@velocity-mongo-mongodb:27017
    If you use the default Bitnami MongoDB, ensure to grant the MongoDB user full write privileges.
    Note: If the MongoDB connection string URL contains authentication or any sensitive information, omit it as a value during install and refer to it as a Kubernetes Secret where the secret must have a key password with a value equal to the MongoDB connection string. In that case, ensure the secrets.database values are the same as the value of the secret name containing the database connection string.
    Note: You can use PluginIndexUrl variable to define the URL for accessing the latest available plugin for Velocity.
  6. Run the helm install command to install the Velocity images into your Kubernetes cluster.
    After you run the command, Kubernetes displays status information about the installation.

What to do next

When all the containers have the status of running, the installation is complete and you can access Velocity at the URL you specified in the Helm chart. You can refresh the status display by using the following kubectl command: kubectl get pods. The default admin user name is admin and the default password is what was specified in the installer.

The following Helm chart parameters for loglevel are optional:
  • ALL
  • DEBUG
  • INFO
  • WARN
  • ERROR
  • FATAL
  • OFF
Note: The default is ALL.