|
|
| (22 intermediate revisions by 2 users not shown) |
| Line 1: |
Line 1: |
| − | {{PEPrerequisites
| + | This page has moved to {{Link-AnywhereElse|product=PEC-REP|version=Current|manual=GCXIPEGuide|topic=PlanningRAA}}. |
| − | |DisplayName=Before you begin
| |
| − | |Context=Find out what to do before deploying Reporting and Analytics Aggregates (RAA).
| |
| − | |LimitationsText=RAA container works with the Genesys Info Mart database. The Genesys Info Mart database scheme must correspond to a compatible Genesys Info Mart version. Execute the following command to discover the required Genesys Info Mart release:
| |
| − | docker run -it --entrypoint /bin/java gcxi/raa:<IMAGE_VERSION> -jar GIMAgg.jar -version
| |
| − | RAA container runs RAA on Java 11, and is supplied with the following of JDBC drivers:
| |
| − | | |
| − | *MSSQL 9.2.1 JDBC Driver
| |
| − | *Postgres 42.2.11 JDBC Driver
| |
| − | *Oracle Database 21c (21.1) JDBC Driver
| |
| − | | |
| − | JDBC driver can be overridden by copying driver file to '''lib\jdbc_driver_<RDBMS>''' (or by making link) in a work dir. See for [https://docs.genesys.com/Documentation/RAA/9.0.0/Dep/PostInstall#JDBCDriverForRAA JDBC driver for RAA] for details.
| |
| − | |HelmText===Init containers==
| |
| − | The RAA Helm chart includes two explicit init containers:
| |
| − | | |
| − | * '''configDelivery init''' -- this container delivers required XML configuration and *.SS files in the RAA working directory. Those files must be available in a GZIP archive, encoded as base64, which must be passed using the Helm install/update option '''--set-file raa.deployment.configTar=config.tar.gz.b64'''. Default '''conf.xml''' and '''user-data-map.ss''' are supplied with the Helm chart. If a GZIP archive is not specified by the '''--set-file''' option, the init container copies them into the working directory (unless they are already present). <br/> The configDelivery init container is optional, and is disabled by default; when it is disabled, you can create RAA configuration files in the mounted config volume. The configDelivery init container makes sense when access to the mounted working directory is restricted for any reason -- often for security reasons, or due to use of ephemeral storage for the configuration volume.
| |
| − | | |
| − | A container name value should be specified to enable configDelivery container.
| |
| − | | |
| − | '''myvalues.yaml'''
| |
| − | <source lang="bash">raa:
| |
| − | ...
| |
| − | statefulset:
| |
| − | ...
| |
| − | containers:
| |
| − | ...
| |
| − | configDelivery:
| |
| − | name: "{{ $.Chart.Name }}-conf-delivery"</source>
| |
| − | ===testRun init container===
| |
| − | testRun - executes all the aggregations on an empty time range. Such the step allows to detect configuration and customisation mistakes before staring the real aggregations because SQL execution (even on empty data) checks the presence of involved tables and columns. This init container is optional and enabled by default. Set testRun empty (nothing after colon) in container section of your values.yaml to disable it.
| |
| − | | |
| − | '''myvalues.yaml'''
| |
| − | <source lang="bash">raa:
| |
| − | ...
| |
| − | statefulset:
| |
| − | ...
| |
| − | containers:
| |
| − | ...
| |
| − | testRun:
| |
| − | name: "{{ $.Chart.Name }}-test-run"</source>
| |
| − | ==Pod containers==
| |
| − | RAA has a couple of execution containers:
| |
| − | | |
| − | ===aggregation container===
| |
| − | aggregation is a required container which does the aggregation work. Only container name is specified in values.yaml.
| |
| − | | |
| − | '''myvalues.yaml'''
| |
| − | <source lang="bash">raa:
| |
| − | ...
| |
| − | statefulset:
| |
| − | ...
| |
| − | containers:
| |
| − | aggregation:
| |
| − | name: "{{ $.Chart.Name }}"
| |
| − | ...</source>
| |
| − | ===monitor container===
| |
| − | monitor is an optional sidecar container which allows execution of RAA tool from file with parameters placed in a work dir (see GCXI-4052 - Add an ability to execute RAA tools in azure without kubectl exec CLOSED ). The function makes sense when kubeclt exec is not allowed by security or other reasons. The container also exposes two ports for scraping of aggregation metrics and health metric by Prometheus or other monitoring tool. Monitor container is optional and disabled by default.
| |
| − | | |
| − | '''myvalues.yaml'''
| |
| − | <source lang="bash">raa:
| |
| − | ...
| |
| − | statefulset:
| |
| − | ...
| |
| − | containers:
| |
| − | ...
| |
| − | monitor:
| |
| − | name: "{{ $.Chart.Name }}-monitor"
| |
| − |
| |
| − | toolcmd:
| |
| − | # interval of checking for a new file with command
| |
| − | intervalSec: "20"
| |
| − |
| |
| − | metrics:
| |
| − | portName: "metrics"
| |
| − | containerPort: "9100"
| |
| − |
| |
| − | health:
| |
| − | portName: "health"
| |
| − | containerPort: "9101"
| |
| − | ...</source>
| |
| − | ==Test containers==
| |
| − | There is a couple of test containers for helm test command. They are listed below according to execution order:
| |
| − | | |
| − | ===testRunCheck container===
| |
| − | testRunCheck waits for execution of testRun init container (if it is still running) and returns a result of test execution. The test is optional and enabled by default. It should be enabled with testRun init container only. Set testRunCheck empty (nothing after colon) in testPod section of your values.yaml to disable it.
| |
| − | | |
| − | '''myvalues.yaml'''
| |
| − | <source lang="bash">raa:
| |
| − | ...
| |
| − | testPods:
| |
| − |
| |
| − | testRunCheck:
| |
| − |
| |
| − | name: "{{ tpl .Values.raa.serviceName . }}-test-run-check"
| |
| − |
| |
| − | container:
| |
| − | name: "{{ $.Chart.Name }}-test-run-check"
| |
| − |
| |
| − | labels: {}
| |
| − |
| |
| − | annotations:
| |
| − | "helm.sh/hook-weight": "100"
| |
| − | "helm.sh/hook": "test-success"
| |
| − | "helm.sh/hook-delete-policy": "before-hook-creation"
| |
| − | ...</source>
| |
| − | ===healthChek test container===
| |
| − | healthCheck executes and returns status of healthCheck. It also prints the content of current configuration files and health files to standard output. The test is optional and enabled by default. Set healthCheck empty (nothing after colon) in testPod section of your values.yaml to disable it.
| |
| − | | |
| − | '''myvalues.yaml'''
| |
| − | <source lang="bash">raa:
| |
| − | ...
| |
| − | testPods:
| |
| − | ...
| |
| − | healthCheck:
| |
| − | name: "{{ tpl .Values.raa.serviceName . }}-health-check"
| |
| − |
| |
| − | container:
| |
| − | name: "{{ $.Chart.Name }}-health-check"
| |
| − |
| |
| − | labels: {}
| |
| − |
| |
| − | annotations:
| |
| − | "helm.sh/hook-weight": "200"
| |
| − | "helm.sh/hook": "test-success"
| |
| − | "helm.sh/hook-delete-policy": "before-hook-creation"
| |
| − | ...</source>
| |
| − | |ThirdPartyText=<div style="background-color: aliceblue; font-style: italic;">List any third-party services that are required (both common across Genesys Engage cloud private edition and specific to <service_name>).</div> | |
| − | |StorageText====GIM secret volume=== | |
| − | RAA mounts as volume secret with GIM connections details when <code class="yml variable">raa.env.GCXI_GIM_DB__JSON</code> is not specified. GIM database connection details can be declared as k8s secret:
| |
| − | | |
| − | '''gimsecret.yaml'''
| |
| − | <source lang="bash">apiVersion: v1
| |
| − | kind: Secret
| |
| − | metadata:
| |
| − | namespace: gcxi
| |
| − | name: gim-secret
| |
| − | type: kubernetes.io/service-account-token
| |
| − | data:
| |
| − | json_credentials: eyJqZGJjX3VybCI6ImpkYmM6cG9zdGdyZXNxbDovLzxob3N0Pjo1NDMyLzxnaW1fZGF0YWJhc2U+IiwgImRiX3VzZXJuYW1lIjoiPHVzZXI+IiwgImRiX3Bhc3N3b3JkIjoiPHBhc3N3b3JkPiJ9Cg==
| |
| − | </source>
| |
| − | and reference in values.yaml
| |
| − | | |
| − | '''myvalues.yaml'''
| |
| − | <source lang="bash">raa
| |
| − | ...
| |
| − | volumes:
| |
| − | ...
| |
| − | gimSecret:
| |
| − | name: "gim-secret-volume"
| |
| − | secretName: "gim-secret"
| |
| − | jsonFile: "json_credentials"
| |
| − | ...</source>
| |
| − | CSI secret can be mounted via secretProviderClass alternatively
| |
| − | | |
| − | '''myvalues.yaml'''
| |
| − | <source lang="bash">raa
| |
| − | ...
| |
| − | volumes:
| |
| − | ...
| |
| − | gimSecret:
| |
| − | name: "gim-secret-volume"
| |
| − | secretProviderClass: "gim-secret-class"
| |
| − | jsonFile: "json_credentials"
| |
| − | ...</source>
| |
| − | | |
| − | ===Config volume===
| |
| − | RAA mounts a config volume as /genesys/raa_config folder inside container. The folder is considered as a work dir and used by RAA for reading of the following files at startup:
| |
| − | | |
| − | * '''conf.xml''' contains configuration of application level config settings (see [https://intranet.genesys.com/display/RP/RAA+configuration+in+Azure RAA configuration in Azure] discovers the details of conf.xml)
| |
| − | * custom '''*.ss''' files (see [https://docs.genesys.com/Documentation/RAA/8.5.0/UG/CustomAgg How Do I Customize Queries and Hierarchies?] for details)
| |
| − | * JDBC driver from lib/jdbc_driver_<RDBMS> (see [https://docs.genesys.com/Documentation/RAA/9.0.0/Dep/PostInstall#JDBCDriverForRAA Procedure: Configuring the JDBC Driver for RAA] for details)
| |
| − | | |
| − | Usually RAA does not create any files here at runtime so the volume does not requires a superfast storage class.
| |
| − | | |
| − | Size limit is set to 50M by default. The storage class and size limit can be specified in values:
| |
| − | | |
| − | '''myvalues.yaml'''
| |
| − | <source lang="bash">raa
| |
| − | ...
| |
| − | volumes:
| |
| − | ...
| |
| − | config:
| |
| − | capacity: 50Mi
| |
| − | storageClassName: "<vendor storage class>"
| |
| − | ...</source>
| |
| − | RAA helm chart creates Persistent Volume Claim. It can also optionally create a Persistent Volume (when <code class="yml variable">raa.volumes.config.pv</code> is specified). See how Persistent Volume declared in helm chart:
| |
| − | | |
| − | '''raa-config-volume.yaml'''
| |
| − | <source lang="bash">{{- with .Values.raa.volumes.config.pv }}
| |
| − | apiVersion: v1
| |
| − | kind: PersistentVolume
| |
| − | metadata:
| |
| − | name: "{{ tpl .name $ }}"
| |
| − | {{- if or ($.Values.raa.labels) (.labels) }}
| |
| − | labels:
| |
| − | {{- with $.Values.raa.labels }}
| |
| − | {{- range $key, $value := . }}
| |
| − | {{ $key }}: "{{ tpl $value $ }}"
| |
| − | {{- end }}
| |
| − | {{- end }}
| |
| − | {{- with .labels }}
| |
| − | {{- range $key, $value := . }}
| |
| − | {{ $key }}: "{{ tpl $value $ }}"
| |
| − | {{- end }}
| |
| − | {{- end }}
| |
| − | {{- end }}
| |
| − |
| |
| − | {{- if or ($.Values.raa.annotations) (.annotations) }}
| |
| − | annotations:
| |
| − | {{- with $.Values.raa.annotations }}
| |
| − | {{- range $key, $value := . }}
| |
| − | {{ $key }}: "{{ tpl $value $ }}"
| |
| − | {{- end }}
| |
| − | {{- end }}
| |
| − | {{- with .annotations }}
| |
| − | {{- range $key, $value := . }}
| |
| − | {{ $key }}: "{{ tpl $value $ }}"
| |
| − | {{- end }}
| |
| − | {{- end }}
| |
| − | {{- end }}
| |
| − |
| |
| − | spec:
| |
| − | accessModes:
| |
| − | - ReadWriteMany
| |
| − | {{- with $.Values.raa.volumes.config }}
| |
| − | capacity:
| |
| − | storage: "{{ .capacity }}"
| |
| − | {{- with .storageClassName }}
| |
| − | storageClassName: "{{ . }}"
| |
| − | {{- end }}
| |
| − | {{- with .pv.vendorSpec}}
| |
| − | {{- toYaml . | nindent 2 }}
| |
| − | {{- end}}
| |
| − | {{- end }}
| |
| − | {{- end }}</source>
| |
| − | It is enough to define <code class="yml variable">Values.raa.volumes.config.storageClassName</code> and a vendor specific part of Persistent Volume (<code class="yml variable">raa.volumes.config.pv.vendorSpec)</code> in values file:
| |
| − | | |
| − | '''myvalues.yaml'''
| |
| − | <source lang="bash">raa
| |
| − | ...
| |
| − | volumes:
| |
| − | ...
| |
| − | config:
| |
| − | storageClassName: "hostpath"
| |
| − | pv:
| |
| − | vendorSpec:
| |
| − | hostPath:
| |
| − | type: Directory
| |
| − | # path for conf.xml, *.ss files and JDBC driver when default is not suitable
| |
| − | path: "/usr/local/genesys/RAA/config/"
| |
| − | ...</source>
| |
| − | Alternatively Persistent Volume can be defined separately. Its name should be specified in values.yaml via <code class="yml variable">raa.volumes.config.pvc.volumeName</code> for binding to Persistent Volume Claim:
| |
| − | | |
| − | '''myvalues.yaml'''
| |
| − | <source lang="bash">raa
| |
| − | ...
| |
| − | volumes:
| |
| − | ...
| |
| − | config:
| |
| − | pv: {}
| |
| − | pvc:
| |
| − | volumeName: "my_raa_config_volume"
| |
| − | ...</source>
| |
| − | An ephemeral storage could be also mapped.
| |
| − | | |
| − | ===Health volume===
| |
| − | RAA uses health volume for the following purposes:
| |
| − | | |
| − | *placing actual health files (see [https://docs.genesys.com/Documentation/RAA/latest/UG/AggProc#Checking_the_health_of_the_aggregate_process Checking the health of the aggregate process] for details)
| |
| − | *place for prometheus file containing metrics for 2-3 scrape intervals behind
| |
| − | *results of recent '''testRun''' init container execution
| |
| − | | |
| − | Size limit is set to 50MB by default. All the purposes assumes periodic interaction with the volume at runtime. Therefore it is not recommended to choose very slow storage class for this volume.
| |
| − | | |
| − | '''myvalues.yaml'''
| |
| − | | |
| − | <source lang="bash">raa
| |
| − | ...
| |
| − | volumes:
| |
| − | ...
| |
| − | health:
| |
| − | capacity: 50Mi
| |
| − | storageClassName: "<vendor storage class>"
| |
| − | ...</source>
| |
| − | RAA helm chart creates Persistent Volume Claim. It can also optionally create a Persistent Volume (when <code class="yml variable">raa.volumes.health.pv</code> is specified). See how Persistent Volume declared in helm chart:
| |
| − | | |
| − | '''raa-config-volume.yaml'''
| |
| − | <source lang="bash">{{- with .Values.raa.volumes.health.pv }}
| |
| − | apiVersion: v1
| |
| − | kind: PersistentVolume
| |
| − | metadata:
| |
| − | name: "{{ tpl .name $ }}"
| |
| − | {{- if or ($.Values.raa.labels) (.labels) }}
| |
| − | labels:
| |
| − | {{- with $.Values.raa.labels }}
| |
| − | {{- range $key, $value := . }}
| |
| − | {{ $key }}: "{{ tpl $value $ }}"
| |
| − | {{- end }}
| |
| − | {{- end }}
| |
| − | {{- with .labels }}
| |
| − | {{- range $key, $value := . }}
| |
| − | {{ $key }}: "{{ tpl $value $ }}"
| |
| − | {{- end }}
| |
| − | {{- end }}
| |
| − | {{- end }}
| |
| − |
| |
| − | {{- if or ($.Values.raa.annotations) (.annotations) }}
| |
| − | annotations:
| |
| − | {{- with $.Values.raa.annotations }}
| |
| − | {{- range $key, $value := . }}
| |
| − | {{ $key }}: "{{ tpl $value $ }}"
| |
| − | {{- end }}
| |
| − | {{- end }}
| |
| − | {{- with .annotations }}
| |
| − | {{- range $key, $value := . }}
| |
| − | {{ $key }}: "{{ tpl $value $ }}"
| |
| − | {{- end }}
| |
| − | {{- end }}
| |
| − | {{- end }}
| |
| − |
| |
| − | spec:
| |
| − | accessModes:
| |
| − | - ReadWriteMany
| |
| − | {{- with $.Values.raa.volumes.health }}
| |
| − | capacity:
| |
| − | storage: "{{ .capacity }}"
| |
| − | {{- with .storageClassName }}
| |
| − | storageClassName: "{{ . }}"
| |
| − | {{- end }}
| |
| − | {{- with .pv.vendorSpec}}
| |
| − | {{- toYaml . | nindent 2 }}
| |
| − | {{- end}}
| |
| − | {{- end }}
| |
| − | {{- end }}</source>
| |
| − | It is enough to define <code class="yml variable">Values.raa.volumes.health.storageClassName</code> and a vendor specific part of Persistent Volume (<code class="yml variable">raa.volumes.health.pv.vendorSpec)</code> in values file:
| |
| − | | |
| − | '''myvalues.yaml'''
| |
| − | <source lang="bash">raa
| |
| − | ...
| |
| − | volumes:
| |
| − | ...
| |
| − | health:
| |
| − | storageClassName: "hostpath"
| |
| − | pv:
| |
| − | vendorSpec:
| |
| − | hostPath:
| |
| − | type: Directory
| |
| − | path: "/usr/local/genesys/RAA/health/"
| |
| − | ...</source>
| |
| − | Alternatively Persistent Volume can be defined separately. Its name should be specified in values.yaml via <code class="yml variable">raa.volumes.health.pvc.volumeName</code> for binding to Persistent Volume Claim:
| |
| − | | |
| − | '''myvalues.yaml'''
| |
| − | <source lang="bash">raa
| |
| − | ...
| |
| − | volumes:
| |
| − | ...
| |
| − | config:
| |
| − | pv: {}
| |
| − | pvc:
| |
| − | volumeName: "my_raa_helath_volume"
| |
| − | ...</source>
| |
| − | An ephemeral storage could be also mapped.
| |
| − | |NetworkText=RAA interacts only with the Genesys Info Mart database.
| |
| − | | |
| − | RAA can expose Prometheus metrics by way of Netcat.
| |
| − | | |
| − | The aggregation pod has it's own IP address, and can run wither one or two running containers. For Helm test, additional IP address are required -- each test pod runs one container.
| |
| − | | |
| − | Genesys recommends that RAA be located in the same region as the Genesys Info Mart database.
| |
| − | |BrowserText=Not applicable.
| |
| − | |DependenciesText=RAA interacts with Genesys Info Mart database only.
| |
| − | |GDPRText=Not applicable.
| |
| − | |PEPageType=bf21dc7c-597d-4bbe-8df2-a2a64bd3f167
| |
| − | }}
| |
This is a draft page; it has not yet been published.
