Installing on Kubernetes#
You can install UrbanCode™ Velocity onto a Kubernetes cluster.
The ID that you use to install the product must be able to make changes to the host environment. 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. UrbanCode 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. UrbanCode Velocity supports the following browsers: Chrome, Firefox, and Edge.
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 you installation environment.
In addition to the requirements for all installation scenarios, the following items are required for Kubernetes or Minikube installation:
- Kubernetes 1.4+ with Beta APIs enabled
- If you want to use Minikube, it must be installed onto a hypervisor appropriate for your operating system. On Linux you might use Oracle Virtual Box; on Windows you might use Hyper-V.
- The CLI that is used for both Minkube and Kubernetes, Kubectl, installed and configured.
- Helm v2.6.0 or later. Helm is the Kubernetes package manager. Helm uses charts to manage Kubernetes resources, such as those that comprise UrbanCode Velocity.
- MongoDB database installed with a persistent volume. Version 3.4 or later is required. Instructions for installing MongoDB are provided below.
- For Minikube, add the Minikube IP address to your hosts file and assign a host name to it. Kubernetes requires a host name rather than a simple IP address. On Linux, the file location is etc/hosts; on Windows, the location is C:\Windows\System32\drivers\etc\hosts.
- If you are using offline installation, you need 4GB free in your
Get a key. The key enables you to complete installation. Visit the UrbanCode Velocity web portal to obtain your key. After completing the form, you can copy the access key. Store the key in a readily-available location; you use it during installation.
Note: Make sure that you select a key for the product version that you want to install. Keys for the Standard Edition do not work with the Community Edition and vice-versa.
You install the product by running the installation script that copies the Helm chart to your environment and sets installation parameters. After the script finishes, you run Kubernetes Helm commands that pull the product images from a GitHub repository and place them into the cluster defined in the Helm chart.
Additionally, you connect your installation to a MongoDB, and configure an SSL certificate. If you are using Minikube, you also need to configure an ingress.
Note: To avoid Windows UAC permission issues, use PowerShell as administrator.
Download the installation file for your environment.
Note: For macOS and Linux installations, set the appropriate permissions before running the file:
sudo chmod +x.
- Linux: https://hcl-velocity-binaries.s3.amazonaws.com/velocity-hcl-install-latest-linux
- Windows: https://hcl-velocity-binaries.s3.amazonaws.com/velocity-hcl-install-latest-win.exe
- Mac OS: https://hcl-velocity-binaries.s3.amazonaws.com/velocity-hcl-install-latest-macos
- Run the downloaded executable file.
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:
At the Please enter your 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.
At the Choose the platform prompt, select
At the Enter the location where the 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
At the Please enter the hostname where you will run 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.
The Helm chart is copied to
/my\_installation/version\_number/velocity-version.tgz. The installation properties are saved in a file located at
If you do not have a MongoDB database installed, install one now. Follow the instructions at the MongoDB GitHub repository.
Below is a sample command for installing the MongoDB:
helm install \ --name velocity-mongo stable/mongodb \ --set database.password=mongo \ --set database.user=mongo \ --set database.name=velocity
Note: If Helm cannot find the chart, try running the following command:
helm repo add stable https://kubernetes-charts.storage.googleapis.com/. If your organization uses a different repository, substitute it for
Note: If you are using Helm 3.0 or later, change the name property to
velocity-mongo, as shown in the following example:
helm install velocity-mongo stable/mongodb \ --set database.password=mongo \ --set database.user=mongo \ --set database.name=velocity
Create an SSL certificate and key and store them in the velocity-secret.yml file.
Create the velocity-secret.yml file.
Paste the following code fragment into your file:
apiVersion: v1 data: tls.crt: <BASE64 Encoded> tls.key: <Base64 Encoded> kind: Secret metadata: name: velocitytls namespace: default type: Opaque
Generate a public key and a private certificate.
You can use OpenSSL to generate the certificate and key, which is installed on most Linux distros. On Windows, the easiest way to get OpenSSL is with Git. Git installs a copy in its Program Files\Git\usr\bin directory. The following example creates a certificate named certificate.pem:
openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 365 -out certificate.pem
Encrypt the certificate.
The following code fragment illustrates how to encrypt the certificate on Linux:
cat certificate.pem | base64
Copy the encrypted certificate and then paste it into the tls.crt field in the velocity-secret.yml file.
Encrypt the private key and paste it into the
tls.keyfield in the velocity-secret.yml file.
Apply velocity-secret.yml file to your installation.
You can use the kubectl command to apply your secret:
kubectl apply -f velocity-secret.yml
If the process is successful, you will see a message similar to the following one:
Enable your ingress and ensure that it points to your host by completing these steps:
For a full Kubernetes installation, you can use the following commands:
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/static/mandatory.yaml kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/static/provider/cloud-generic.yaml
If you are using Minikube, use the following command to enable the ingress:
minikube addons enable ingress.
Determine the configuration properties for the helm install command.
values.yamlfile is located in
/my\_installation/version\_number/velocity-version.tgz. The following code fragment displays a typical command:
helm install \ --name uc-velocity \ ./velocity-<version\>-helm.tgz \ --set access.key=my\_access\_key \ --set license=accept \ --set url.domain=my\_hostname \ --set mongo.url=mongodb://mongo:mongo@velocity-mongo-ibm-mongodb-dev:27017/velocity
If you are using Helm 3.0 or later, remove the name property as shown in the following example:
helm install uc-velocity \ ./velocity-<version\>-helm.tgz \ --set access.key=my\_access\_key \ --set license=accept \ --set url.domain=my\_hostname \ --set mongo.url=mongodb://mongo:mongo@velocity-mongo-ibm-mongodb-dev:27017/velocity
Properties depend on your environment. The following properties are required. The optional properties are given later.
The product access key obtained earlier.
The hostname of your node or the Ingress host name.
The URL of the MongoDB. Specify the following parameters.
The user ID to authenticate with the MongoDB database. For example, mongo.
The associated password to authenticate with the MongoDB database. For example, mongo.
The port number for the MongoDB database. Use the value shown in the example, which is 27017.
The MongoDB URL or the MongoDB service name if it is running within the Kubernetes cluster. For example, velocity-mongo-ibm-mongodb-dev.
The name of the database to be used by UrbanCode™ 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.
If you use the default HCL MongoDB, make sure to grant the MongoDB user full write privileges.
The name space where the Helm chart is applied, and the name of Helm chart. Deprecated for Helm 3.0 or later.
--name uc-velocity ./velocity-<version\>-helm.tgz
helm installcommand to install the UrbanCode Velocity images into your Kubernetes cluster.
After you run the command, Kubernetes displays status information about the installation.
Refer to the displayed NOTES section for the location of the Minikube administrator dashboard. You manage your Minikube installation on the admin dashboard.
When all the containers have the status of
running, the installation is complete and you can access UrbanCode 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 admin.
The following Helm chart parameters are optional:
A random string or GUID that is used verify the authenticity of API calls and data.
Automates license acceptance. Use the value accept to accept the license.
A 32-byte Hex that is used verify the authenticity of API calls and data.
A 32-byte Hex that is used verify the authenticity of API calls and data.
The level of logging. Values for this property are: all, debug, info, warn, error, fatal, and off. The default is all.
Parent topic: Installation