Installing on Kubernetes

You can install HCL™ Accelerate on Kubernetes cluster.

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. HCL™ Accelerate 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. HCL™ Accelerate 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, the following items are required for Kubernetes or Minikube installation:

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 Minikube 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 HCL™ Accelerate.
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.

About this task

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

Additionally, you can configure an SSL certificate. If using Minikube, you also need to configure Ingress.

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 Kubernetes administrator.

Procedure

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 version 4.0:
```
     helm install accelerate-mongo \
     --set persistence.enabled=false \
     --set image.tag=4.0 \ bitnami/mongodb
```
Note: To install MongoDB version 4.2, change the --set image.tag=4.2
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 accelerate-mongo
To list all pods in the namespace, use the following command:
kubectl get pods

If password not specified during Helm install, use the command below to get the dynamically generated encrypted password.
kubectl get secrets accelerate-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.
Enable your ingress and ensure that it points to your host by completing these steps:
1. For a full Kubernetes installation, you can use the following two commands:
```
helm repo add bitnami https://charts.bitnami.com/bitnami
```
```
helm install accelerate-ingress bitnami/nginx-ingress-controller --version 8.0.8
```
2. If you are using Minikube, use the following command instead to enable the ingress: minikube addons enable ingress.
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:
```
./<accelerate-installation-file> --license=accept
```
1. At the Please enter your HCL Accelerate 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 HCL Accelerate 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 HCL™ Accelerate 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 HCL Accelerate 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.
8. To enforce limits on resources, set the values for the resource flags for all containers and use the customConfigFile flag to set the path of the JSON file that contains values that are specified for individual services.
  An example of an install command using the new flags follows:
  /accelerate-hcl-install-1-5-5-macos --resourcesRequestsCpu 60m --customConfigFile resources.json
  You can use the following flags in the command:
  - resourceLimitsMemory
  - resourceLimitscpu
  - resourceRequestMemory
  - resourceRequestcpu
  - customConfigFile
  Note: A resources.json code example follows.
```
{
  "resources": {
    "limits": {
      "memory": {
        "default": "1Gi",
        "application-api": "3Gi"
      },
      "cpu": {
        "application-api": "2"
      },
    },
    "requests": {
      "memory": {
        "release-events-ui": "256Mi"
      },
      "cpu": {
        "multi-app-pipeline-api": "45m",
        "release-events-ui": "55m"
      }
    }
  }
}
```
  Note: The Helm chart is copied to /my_installation/version_number/accelerate-version.tgz. The installation properties are saved in a file located at /home/ucv/settings.json.
If using a custom SSL certificate, create an SSL certificate and key and store them in an accelerate-custom-tls-secret.yaml file.
1. 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
```
2. Create the accelerate-custom-tls-secret.yaml file.
  Paste the following code fragment into your file:
```
      apiVersion: v1
     data:
       tls.crt: <BASE64 Encoded>
       tls.key: <Base64 Encoded>
     kind: Secret
     metadata:
       name: accelerate-custom-tls
       namespace: default
     type: Opaque
         
```
  Note: Ensure the code does not contain any line breaks.
3. Encrypt the certificate.
  The following code fragment illustrates how to encrypt the certificate on Linux:
```
cat certificate.pem | base64
```
4. Copy the encrypted certificate and then paste it into the tls.crt field in the accelerate-custom-tls-secret.yaml file.
5. Encrypt the private key and paste it into the tls.key field in the accelerate-custom-tls-secret.yaml file.
6. Apply accelerate-custom-tls-secret.yaml file to your installation.
  You can use the kubectl command to apply your secret:
```
kubectl apply -f accelerate-custom-tls-secret.yaml
```
  If the process is successful, you will see a message similar to the following one:
```
secret/accelerate-custom-tls created
```
Note: If you are installing HCL™ Accelerate 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 accelerate \
     ./accelerate-<version>-helm.tgz \
     --set access.key=my_access_key \
     --set license=accept \
     --set url.domain=my_hostname \
     --set mongo.url=mongodb://root:password@accelerate-mongo-mongodb:27017
```
Note: The unique name accelerate 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.

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@accelerate-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, accelerate-mongo-mongodb.

database_name

The name of the database to be used by HCL™ Accelerate. For example, accelerate.
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@accelerate-mongo-mongodb:27017

If you use the default Bitnami MongoDB, make sure to grant the MongoDB user full write privileges.
If using a custom SSL certificate, create a custom tls secret as detailed previously, and add --set secrets.tls=accelerate-custom-tls to the Helm install command, where accelerate-custom-tls should be replaced with the name of the secret containing the custom SSL certificate.

Optional: If you need to enforce limits on Argo resources, modify the executor parameter in the accelerate/templates/workflow-controller-configmap.yaml file.

For example, to limit ephemeral Argo pods, you might use the following parameter values:


     ...
     data:
       config: |
         containerRuntimeExecutor: kubelet
         namespace: accelerate
         executor:
           resources:
             limits:
               cpu: 1
               memory: 2Gi
             requests:
               cpu: 50m 
               memory: 512Mi

Run the helm install command to install the HCL™ Accelerate 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.

What to do next

When all the containers have the status of running, the installation is complete and you can access HCL™ Accelerate 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.