Having completed the preparations, it is now time to install Usage Engine Private Edition.

Main Installation Example

In this main installation example, it is assumed that the following optional resources have been added while preparing for the installation (see Kubernetes Cluster Add-ons - Azure (4.2)):

ingress-nginx-controller
cert-manager

Example Certificate

Since cert-manager is being used to provide TLS to the Usage Engine Private Edition installation in this example, you need to create an issuer in order to generate the required certificate.

Here we are going to use an ACME issuer type that is configured to match the Kubernetes cluster that was set up previously in the Preparations - Azure (4.2) chapter:

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: example-issuer
spec:
  acme:
    # The ACME server URL
    server: https://acme-v02.api.letsencrypt.org/directory
    # Email address used for ACME registration
    # You must replace this email address with your own.
    # Let's Encrypt will use this to contact you about expiring
    # certificates, and issues related to your account.
    email: <your valid email address>
    # Name of a secret used to store the ACME account private key
    privateKeySecretRef:
      name: example-issuer-account-key
    solvers:
    - dns01:
        azureDNS:
          resourceGroupName: <azure_resource_group from terraform output>
          subscriptionID: <azure_subscription_id from terraform output>
          hostedZoneName: <aks_domain_zone_name from terraform output>
          environment: AzurePublicCloud
          managedIdentity:
            clientID: <cert_manager_client_id from terraform output>

Observe:

Set email to your email address of choice.
resourceGroupName, subscriptionID, hostedZoneName and clientID can be found in the terraform output from Set Up Kubernetes Cluster - Azure (4.2) | Create Basic Cluster and additional infrastructure section.

Assuming that the issuer spec above has been saved into a file called example-issuer.yaml, it can be created by running the following command:

kubectl apply -f example-issuer.yaml

Application Gateway TLS Certificate

With ClusterIssuer setup properly, we can proceed to generate TLS Certificate for the Application Gateway that was created in Set Up Kubernetes Cluster - Azure (4.2) | Create Basic Cluster and additional infrastructure section.

To generate a certificate, create a yaml file named certificate.yaml with the following contents:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: lb-cert
spec:
  commonName: <aks_domain_zone_name from terraform output>
  dnsNames:
    - <aks_domain_zone_name from terraform output>
    - desktop-online.<aks_domain_zone_name from terraform output>
    - platform.<aks_domain_zone_name from terraform output>
    - ingress.<aks_domain_zone_name from terraform output>
    - grafana.<aks_domain_zone_name from terraform output>
  issuerRef:
    kind: ClusterIssuer
    name: example-issuer
  secretName: lb-cert

Execute the yaml file by running the following command:

kubectl apply -f certificate.yaml -n uepe

Wait for a while and then confirm certificate has been generated successfully by running the following command:

kubectl get certificate -n uepe

The output shows the certificate named lb-cert status is ready, similar to below:

NAME                        READY   SECRET                              AGE
lb-cert                     True    lb-cert                             46h

Install Helm Chart

Although the number of helm value combinations you can set is virtually endless, some values should more or less always be set.

Start by creating a file called uepe-values.yaml, and in that file, specify a minimal set of values that will serve as a good starting point as shown below:

azure:
  appgw:
    secret: lb-cert
environment: azure
global:
  domain: <aks_domain_zone_name from terraform output>
  imagePullSecrets:
  - name: ecr-cred
  ingressController:
    serviceName: ingress-nginx-controller
licenseKey: <insert-your-license-key-string-here>
log:
  format: json
platform:
  db:
    type: postgresql
  tls:
    cert:
      public: certManager
    certManager:
      public:
        issuer:
          kind: ClusterIssuer
          name: example-issuer
    enabled: true    
postgres:
  adminUsername: <db_username from terraform output>
  host: <db_endpoint from terraform output>
  port: 5432
persistence:
  enabled: true
  existingClaim: <PVC name from manifests/storage_persistence.yaml file>

The information in the following table will help you determine the values to set in your particular installation:

Value	Comment

Value	Comment
`azure.appgw.secret`	This value should be set to match to the load balancer certificate secret name created in Applicate Gateway TLS Certificate section.
`global.domain`	This value should be set to match the `aks_domain_zone_name` listed in the terraform output produced in the Set Up Kubernetes Cluster - Azure (4.2) \| Create Basic Cluster and additional infrastructure section.
`global.imagePullSecrets`	This value references an image pull secret containing the credentials required to pull container images from the Digital Route AWS ECR registry. If you are hosting the container images in your own container registry, depending on how that is configured, another image pull secret will probably be needed, see https://infozone.atlassian.net/wiki/spaces/UEPE4D/pages/277676052/General+Usage+Engine+Private+Edition+Preparations+4.2#Container-Images for additional information.
`global.ingressController.serviceName`	This is the name of the Kubernetes `Service` that was created adding the Ingress NGINX Controller.
`licenseKey`	This is the license key that can be found in the `licenseKey` file that you have previously received (see the https://infozone.atlassian.net/wiki/spaces/UEPE4D/pages/161481605/General+Pre-requisites#License section).
`log.format`	If you need to use dedicated log collection and monitoring tools like Fluent-bit, Elasticsearch, Kibana or AWS CloudWatch for Usage Engine Private Edition, ensure the log format is configured to `json`. See https://infozone.atlassian.net/wiki/x/Q4BDD for additional information.
`platform.tls.*`	These values are set to use the example issuer created at the beginning of this chapter. This should only be seen as an example and the values should be adjusted according to the real world situation.
`platform.tls.certManager.public.issuer.domain`	Should be set to match the `eks_domain_zone_name` listed in the terraform output produced in the Set Up Kubernetes Cluster - Azure (4.2) \| Create Basic Cluster and additional infrastructure section.
`platform.db.type`	Set to match the RDS PostgreSQL service that was created in the Set Up Kubernetes Cluster - Azure (4.2) \| Create Basic Cluster and additional infrastructure section. If another database service is being used, the value must be adjusted accordingly.
`postgres.adminUsername`	This value is taken from the `db_username` listed in the terraform output produced in the Set Up Kubernetes Cluster - Azure (4.2) \| Create Basic Cluster and additional infrastructure section.
`postgres.host`	This value is taken from the first part of the `db_endpoint` listed in the terraform output produced in the Set Up Kubernetes Cluster - Azure (4.2) \| Create Basic Cluster and additional infrastructure section.

Note!

General documentation of the values above is provided in the values.yaml file in the usage-engine-private-editionhelm chart.

Note!

In this example, the following assumptions have been made:

PostgreSQL is used as the system database.
It is assumed that you have previously bootstrapped the postgresqlPassword secret key with a value equal to the db_password configured in the terraform.tfvars file. For instructions on how to do this, see https://infozone.atlassian.net/wiki/spaces/UEPE4D/pages/251560020/Usage+Engine+Private+Edition+Preparations+-+Azure+4.2#Bootstrapping-System-Credentials-%5BinlineExtension%5D.
The system database is automatically created during installation.
jdbcPassword and mzownerPassword are randomly generated.
postgresqlPassword / oraclePassword / saphanaPassword is not randomly generated and therefore must be created as secret as described in point 3.
If you are using the database tool uepe-sys-db-tool.jar to create the system database manually, ensure that the credentials mentioned in point 5 and 6 are included in the secret. For more details, see https://infozone.atlassian.net/wiki/spaces/UEPE4D/pages/251560020/Usage+Engine+Private+Edition+Preparations+-+Azure+4.2#Bootstrapping-System-Credentials-%5BinlineExtension%5D.

Use the following command to install Usage Engine Private Edition:

helm install uepe digitalroute/usage-engine-private-edition --version <version> -f uepe-values.yaml -n uepe

Where <version> is the version of Usage Engine Private Edition to install. For example 4.0.0.

Check that all pods are running and that all pod containers become ready by running the following command:

kubectl get pods -n uepe

This may take a little while but should eventually look similar to this:

NAME                                                READY   STATUS    RESTARTS   AGE
desktop-online-6cdc7c6f9b-qtjwb                     1/1     Running   0          2m40s
external-dns-644cb65c58-pg7gg                       1/1     Running   0          53m
ingress-azure-5d4f68984f-gtqrh                      1/1     Running   0          57m
ingress-nginx-controller-c76dddbc6-sngmx            1/1     Running   0          49m
platform-0                                          1/1     Running   0          2m40s
uepe-operator-controller-manager-5bcc9746cb-4wkz8   2/2     Running   0          2m40s
uepe-operator-controller-manager-5bcc9746cb-rbdtl   2/2     Running   0          2m40s

To get the Desktop Online web user interface hostname run the following command:

kubectl get ingress -n uepe

The output shows FQDN hostname, IP address and port to access Desktop Online.

NAME                       CLASS                       HOSTS                                                        ADDRESS         PORTS     AGE
desktop-online             azure-application-gateway   desktop-online.example-cluster.stratus.az.digitalroute.net   52.187.50.128   80, 443   3m17s
ingress-nginx-controller   azure-application-gateway   ingress.example-cluster.stratus.az.digitalroute.net          52.187.50.128   80, 443   3m17s

Desktop Online should now be accessible at:
https://desktop-online.example-cluster.stratus.digitalroute.net/
Note that it may take a little while before the DNS record gets registered.

The Usage Engine Private Edition installation is now complete.

Other Common Installation Configurations

Bellow are a few common installation configurations for the Usage Engine Private Edition helm chart.

These should be seen as variations of the main installation example outlined above.

Persistent File Storage

Reference Arbitrary PVC

Usage Engine Private Edition can be configured to reference an arbitrary persistent volume claim by setting the following helm values:

persistence:
  enabled: true
  existingClaim: my-pvc

In this example, my-pvc is an arbitrary persistent volume claim that you have created beforehand.