Having When you have completed the preparations , it is now time you can proceed 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 - OCI (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 In this example, 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 - OCI (4.2) chapter:
Code Block | ||
---|---|---|
| ||
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 email:replace <yourthis email address with ofyour choice>own. # NameLet's ofEncrypt awill secretuse usedthis to storecontact theyou ACMEabout accountexpiring private # 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: webhook: groupName: acme.d-n.be solverName: oci config: ociProfileSecretName: oci-profile |
...
Code Block |
---|
apiVersion: v1 kind: Secret metadata: name: oci-profile type: Opaque stringData: tenancy: "your tenancy ocid"<tenancy_ocid from terraform output> user: "your user ocid"<user_ocid configured in terraform.tfvars> region: "your region"<region from terraform output> fingerprint: <fingerprint "yourconfigured key fingerprint"in terraform.tfvars> privateKey: | -----BEGIN RSA PRIVATE KEY----- ...KEY DATA HERE... -----END RSA PRIVATE KEY----- privateKeyPassphrase: "private keys passphrase or empty string if none" |
Create the secret prior to ClusterIssuer creation. To install secret oci-profile
to cert-manager namespace run the following command:
Code Block |
---|
kubectl apply -f oci-profile.yaml -n cert-manager |
Assuming that the issuer spec above has been saved into a file called example-issuer.yaml
, it can be created like thisyou can create it by running the following command:
Code Block | ||
---|---|---|
| ||
kubectl apply -f example-issuer.yaml |
Load Balancer TLS Certificate
With ClusterIssuer setup properly, we can proceed to generate TLS Certificate and import into OCI Certificates Service.
To generate certificate, create a yaml file named certificate.yaml
with the following contents:
Code Block |
---|
apiVersion: cert-manager.io/v1 kind: Certificate metadata: name: lb-cert spec: commonName: <cluster_dns_zone_name listed in thefrom terraform output> dnsNames: - <cluster_dns_zone_name listedfrom in the terraform output> - desktop-online.<cluster_dns_zone_name listed infrom the terraform output> - platform.<cluster_dns_zone_name listed in thefrom terraform output> - ingress.<cluster_dns_zone_name listedfrom in the terraform output> - grafana.<cluster_dns_zone_name listedfrom in the terraform output> issuerRef: kind: ClusterIssuer name: example-issuer secretName: lb-cert |
Execute the yaml file by running the following command:
Code Block |
---|
kubectl apply -f certificate.yaml -n uepe |
Wait for a while and confirm that the certificate has been generated successfully .by running the following command:
Code Block |
---|
kubectl get certificate -n uepe |
The output shows will show that the certificate named
lbcert
’s status is ready
...
Extract the server certificate and CA certificate from secret
lbcert
by running the following command:
Code Block |
---|
kubectl get secrets lb-cert -n uepe -o yaml | yq '.data' | grep "tls.crt" | awk -F : '{print $2}'| tr -d " "|base64 -d > tls.crt |
Separate server certificate and CA certificate into two files by running the following command:
Code Block |
---|
csplit tls.crt '/^-----BEGIN CERTIFICATE-----$/' |
Rename first generated file as server certificate file by running the following command:
Code Block |
---|
mv xx00 tls.crt |
Rename second generated file as CA certificate file by running the following command:
Code Block |
---|
mv xx01 ca.crt |
Extract the private key from secret
lbcert
by running the following command:
Code Block |
---|
kubectl get secrets lb-cert -n uepe -o yaml | yq '.data' | grep "tls.key" | awk -F : '{print $2}'| tr -d " "|base64 -d > tls.key |
By now, The server certificate, CA certificate and private key are now stored in tls.crt
, ca.crt
and tls.key
respectively. Next The next step is to import them into the OCI Certificates Service.
...
Note!
You do not need to import the server certificate, CA certificate and private key into the OCI Certificate Service anymore if OCI Native Ingress controller version 1.3.8 and above is installed.
...
The load balancer TLS certificate can be obtained from Ingress secret internally.
This helm chart property oci.certificates.enabled
must then be set to false
...
when following the Install Helm Chart section. The helm chart property oci.certificates.id
can be omitted.
Skip the next section and proceed to TLS Backendset Secret section.
Import into OCI Certificates Service
Go to the OCI console management , and search for Certificates service. On the Certificates service page, click Create Certificate and follow these steps:
Select Certificate Type Imported and key in a unique name.
Click Next to go to Certificate Configuration page.
Upload the
tls.crt
,ca.crt
andtls.key
files according to table below respectively :
OCI Certificates Configuration | file to upload |
---|---|
Certificate |
|
Certificate Chain |
|
Private Key |
|
Click Next and proceed to Create Certificate.
Wait for the certificate to be created.
Copy and save the certificate’s ocid. This ocid will be set to the
oci.certificates.id
property in the helm chart value file in the next section.
TLS Backendset Secret
The SSL configuration between the load balancer and the backend servers (worker nodes) in the backend set is known as backend SSL. In this case, the backend set is referring to the Platform Pod on the worker nodes. To implement backend SSL, you store the SSL certificates and private key in the form of a Kubernetes secret.
You already have server certificate, The CA certificate and private key generated from the previous section . These certificates and private key can be reused to generate the Kubernetes secret needed by the backend set.
To store the certificate and the private key as a secret in Kubernetes, run the following command:
Code Block |
---|
kubectl create secret generic ca-ser-secret -n uepe --from-file=tls.crt=tls.crt --from-file=tls.key=tls.key --from-file=ca.crt=ca.crt |
Now, the The backend set secret named ca-ser-secret
has now been created in the namespace uepe
.
Info |
---|
Note |
Note! These secret names |
Install Helm Chart
...
the Usage Engine Private Edition helm chart. If you intend to use a different secret name, these helm chart properties MUST be set in
|
Install Helm Chart
Although the number of helm value combinations to set is virtually endless, there are some values should more or less practically always be set.
So let’s start 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:
Code Block |
---|
Info |
In the example below, it is assumed that you have configured the Postgres admin password through a secret. If you have not done so, see https://infozone.atlassian.net/wiki/spaces/UEPE4D/pages/211091666/Usage+Engine+Private+Edition+Preparations+-+OCI+4.2#Bootstrapping-System-Credentials-%5BinlineExtension%5D for guidance. |
Code Block | ||
---|---|---|
| ||
oci: certificates: idenabled: ocid1.certificate.oc1.eu-frankfurt-1.amaaaaaaqpnxi2aaftofigjmkytoomv2u2ycjenhvqsbarhfhpycfujihyyqfalse backendNSG: ocid1.networksecuritygroup.oc1.eu-frankfurt-1.aaaaaaaaephkmmm3hsyqw57wvkfssqlc56ddj7yknhgz7cgajxijvhqkzflq<backend_nsg from terraform output> healthcheck: desktoponline: port: 9001 ingressnginx: port: 443 environment: oci global: domain: <cluster_dns_zone_name from domain: example-cluster.stratus.oci.digitalroute.netterraform output> ingressController: serviceName: ingress-nginx-controller imagePullSecrets: - name: ecr-cred licenseKey: VGhpcyBpcyBhIGZha2UgVXNhZ2UgRW5naW5lIFByaXZhdGUgRWRpdGlvbiBsaWNlbnNlIGtleSE=<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: postgres host: example-cluster-db-primary.postgresql.eu-frankfurt-1.oc1.oraclecloud.com port: 5432 : <db_endpoint from terraform output> port: <db_port from terraform output> persistence: enabled: true existingClaim: fss-pvc |
Here follows Below you can find information on how you can determine the values to set in your particular installation:
Value | Comment |
---|---|
| This value |
indicates if you to use OCI SSL certificate or Kubernetes secret for Load Balancer SSL termination. |
The default value is |
Set it to |
| |
| This value should be set to match the ocid of certificate created in previous section, Import-into-OCI-Certificates-Service. |
This value is not in used if |
|
This value is taken from the | |
| This is the desktop-online backend set health check |
port, 9001. | |
| This is the ingress nginx backend set health check port, |
443. |
| This is the name of the Kubernetes |
|
This value is taken from the | |
| This is referencing an image pull secret containing the credentials required in order to pull container images from the |
DigitalRoute AWS ECR registry. If you are hosting the container images in your own container registry, another image pull secret might be needed, depending on how |
it is configured. See General Usage Engine Private Edition Preparations (4.2) for additional information. | |
| This is the license key that can be found in the |
licenseKey
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, make sure the log format is configured to json
. See Configure Log Collection, Target, and Visualization - OCI 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.
postgres.adminUsername
db_admin_user
General+Pre-requisites#License section. | |
| 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 that the log format is configured to |
| These values are set to use the example issuer created at the beginning of this page. This should only be seen as an example and the values should be adjusted according to the real world scenario. |
| This value is taken from the |
| This value is taken from the |
| This value is taken from the |
postgres.host
Value is taken from the db_endpoint
listed in the terraform output produced in the Set Up Kubernetes Cluster - OCI | Create-Basic-Cluster-and-additional-infrastructure section.
postgres.port
Value is taken from the db_port
listed in the terraform output produced in the Set Up Kubernetes Cluster - OCI | Create-Basic-Cluster-and-additional-infrastructure section.
persistence.existingClaim
The persistent volume claim name created in previous section OCI-Add-ons | oci-file-service-storage | Static Provisioning.
Ignore if persistence.enabled
is false
Info |
---|
General documentation of the values above is provided in the |
...
. | |
| The persistent volume claim name created in previous section OCI-Add-ons | oci-file-service-storage | Static Provisioning. Ignore if |
Info |
---|
General information about the values above is provided in the |
Note |
---|
In the example presented below, the following assumptions have been made:
|
The command below can be used You can use the following command to install Usage Engine Private Edition:
...
Where <version>
is the version of Usage Engine Private Edition to install. For , for example 4.0.0
.
Check that all pods are running and that all pod containers become ready (this may take a little while)by running the following command:
Code Block |
---|
kubectl get pods -w -n uepe NAME READY STATUS RESTARTS AGE desktop-online-5fdd4df85b-5hc6z 1/1 Running 0 97m external-dns-54fb5cb46b-4lfld 1/1 Running 0 27h ingress-nginx-controller-7477648b4c-sz2nw 1/1 Running 0 27h oci-native-ingress-controller-6cd8cf8d79-dz8zp 1/1 Running 0 29h platform-0 1/1 Running 0 97m uepe-operator-controller-manager-69c4b499c8-h9l8w 2/2 Running 0 97m uepe-operator-controller-manager-69c4b499c8-hxdcb 2/2 Running 0 97m |
This may take a little while
To get the Desktop Online web user interface hostname run the following command:
Code Block |
---|
kubectl get ingress -n uepe |
The output shows the FQDN hostname, IP address and port to access the desktop online web user interface.
Code Block |
---|
NAME CLASS HOSTS ADDRESS PORTS AGE desktop-online native-ic-ingress-class desktop-online.example-cluster.stratus.oci.digitalroute.net 130.162.252.220 80 99m ingress-nginx-controller native-ic-ingress-class ingress.example-cluster.stratus.oci.digitalroute.net 130.162.252.220 80 99m |
...
99m |
You should now be able to access the Desktop Online user interface should now be accessible at:
https://desktop-online.example-cluster.stratus.oci.digitalroute.net/
Note that it It may take a little while before the DNS record gets registered.
Insert excerpt | ||||||||
---|---|---|---|---|---|---|---|---|
|
Other Common Installation Configurations
Here follows Bellow are a few common installation configurations for the Usage Engine Private Edition helm chart.
They should be seen as variations to the main installation example outlined above.
Persistent File Storage
If you have chosen selected to prepare for persistent file storage, there are two different ways of configuring your Usage Engine Private Edition installation to use it.
Use Bundled OCI Specific PVC
Specifically for OCI, the Usage Engine Private Edition helm chart contains a bundled persistent volume claim. This persistent volume claim is using the fss-dyn-storage
storage class. To enable it, simply set the following helm values:
...
Where the persistence.bundledClaim.storageRequest
value is used to control the size of the requested storage (default is 1Gi).
Use a command like this You can use the following command to inspect the persistent volume claim that gets created as a result of setting the above helm values:
Code Block | ||
---|---|---|
| ||
kubectl get persistentvolumeclaims mz-bundled-pvc -o yaml |
Reference Arbitrary PVC
Usage Engine Private Edition can be configured to reference an arbitrary persistent volume claim by setting the following helm values:
...
In this example, my-pvc
is an arbitrary persistent volume claim that you have created before hand.
Insert excerpt | ||||||||
---|---|---|---|---|---|---|---|---|
|