Installing the Analytics subsystem into a Kubernetes environment

Use the Install Assist utility program with the APICUP installer to install the Analytics subsystem into your Kubernetes runtime environment.

1. The commands for installing the Analytics subsystem are described in the following table. Sample code is also provided.
   Important: There are known GlusterFS issues that affect the following functionality areas:

   • Elasticsearch, which is used in the API Connect analytics service.
   • The Developer Portal service.

   If you use GlusterFS, you might encounter severe performance degradation and, in some cases, loss of data.

   Note: Host names and DNS entries may not be changed on a cluster after the initial installation.

   Command	Values/Definition
   apicup init	Initializes the apicup installation utility and creates the apiconnect-up.yml configuration file.
   apicup subsys create analyt analytics --k8s	Describes an analytics subsystem in the Kubernetes cluster. The identifier analyt is the name you have assigned to your analytics service. You can assign it any name, as long as the identifier consists of lower case alphanumeric characters or '-', with no spaces, starts with an alphabetic character, and ends with an alphanumeric character. The command analytics indicates that you are creating an analytics subsystem.
   apicup subsys set analyt extra-values-file	<path/file name> - Path to the extra values file. One extra values file is permitted. The extra values file requires a .yaml format. It contains the ingress annotations and other settings for the subsystem. For an example of an extra values file for each subsystem, see Creating an extra values file in a Kubernetes environment. For the ingestion-only configuration, specify the URL of the offload endpoint where all analytics data will be routed. You can choose the name for the file, but you must use .yaml as the file-name extension. Format the file as shown in the following example, making sure to include required settings for the third-party system. apic-analytics-ingestion: outputOffload: |- elasticsearch { hosts => "http://offload_endpoint_URL:port" index => "api-call" }
   apicup subsys set analyt analytics-ingestion	<ai>.<hostname>.<domainname> - The analytics-ingestion endpoint is used by the Gateway service to push data to the Analytics service. All endpoints have to be resolvable by DNS. Domain names that are used for endpoints cannot contain the underscore "_" character. See Pre-installation requirements. Refer to the deployment overview diagram for information about endpoints and certificates: Deployment overview for endpoints and certificates.
   apicup subsys set analyt ingestion-only=true	This setting is required for the ingestion-only configuration, and the value must be set to true.
   apicup subsys set analyt analytics-client	<ac>.<hostname>.<domain name> - The management endpoint that is defined by analytics-client, for example, <ac>.<hostname>.<domain name>. This is the analytics service endpoint used by Cloud Manager, API Manager, and the Portal to communicate with the analytics service and is entered when configuring an analytics service in Cloud Manager. See Registering an analytics service. All endpoints have to be resolvable by DNS. Domain names that are used for endpoints cannot contain the underscore "_" character. See Pre-installation requirements. This setting is not needed for the ingestion-only configuration. For more information, see the note that follows this table.
   apicup subsys set analyt namespace	<namespaceName> - Defines the namespace where the analytics service resides; every subsystem can be in a separate namespace. Valid namespaces are configured in Kubernetes prior to starting the API Connect installation
   apicup subsys set analyt registry	<registry-uri> - The location where you are running the image registry (for example, Artifactory).
   apicup subsys set analyt registry-secret	For example, <registrySecret> - Kubernetes secret with Docker credentials to authenticate with the image registry. The value for registry-secret must match the name of the secret created using the kubectl create secret command. It contains the Docker credentials for accessing the registry.
   apicup subsys set analyt coordinating-max-memory-gb	The default is 6GB. The recommended minimum is 12GB. The actual value will depend upon your environment. This setting is not needed for the ingestion-only configuration. For more information, see the note that follows this table.
   apicup subsys set analyt data-max-memory-gb	The default is 6GB. The recommended minimum is 12GB. The actual value will depend upon your environment. This setting is not needed for the ingestion-only configuration. For more information, see the note that follows this table.
   apicup subsys set analyt data-storage-size-gb	The default is 200GB. The recommended minimum is 200GB. The actual value will depend upon your environment. The data-storage-size-gb value is the amount of storage used per pod. A default installation will contain three data pods. In this example, 600GB of total space is required for the data nodes. This setting is not needed for the ingestion-only configuration. For more information, see the note that follows this table.
   apicup subsys set analyt master-max-memory-gb	The default is 6GB. The recommended minimum is 12GB. The actual value will depend upon your environment. This setting is not needed for the ingestion-only configuration. For more information, see the note that follows this table.
   apicup subsys set analyt master-storage-size-gb	The default is 5GB. The recommended minimum is 5GB. The actual value will depend upon your environment. This setting is not needed for the ingestion-only configuration. For more information, see the note that follows this table.
   apicup subsys set analyt enable-message-queue	Options are true or false. The default is false. When set to true, the message queue will be activated and the analytics pipeline will be configured to use it. See Configuring the analytics message queue. The message queue requires at least one 5GB PVC for each pod.
   apicup subsys set analyt storage-class	<storageClass> - Refers to a valid StorageClass object in your Kubernetes cluster that supports dynamic PersistentVolume provisioning. Static or manual PersistentVolume provisioning can be used, but it requires additional steps not covered in this documentation. You can use local storage or block storage. For block storage, select a block storage format of your choosing in order for API Connect components to be supported. GlusterFS is not recommended as a storage option due to severe performance degradation. For AWS, the gp2 and io1 types of Elastic Block Storage (EBS) are supported. Note that NFS is not supported.
   apicup subsys set analyt es-storage-class	<es-storageClass> - Optional ElasticSearch storage class. If the es-storage-class is set, analytics storage ignores other storage classes and uses the es-storage-class. If not set, then analytics storage uses the storage class object set by the apicup subsys set analyt storage-class command. This setting is not needed for the ingestion-only configuration. For more information, see the note that follows this table.
   apicup subsys set analyt mq-storage-class	<mq-storageClass> - Optional message queue storage class. If the mq-storage-class is set, the message queue ignores other storage classes and uses the mq-storage-class. If not set, then the message queue uses the storage class object set by apicup subsys set analyt storage-class.
   apicup subsys set analyt mode	Determines whether the installation is for development, testing, and demo purposes or for production. If not explicitly set, the mode will default to dev (development and testing) for versions 2018.4.1.4 and later. For versions 2018.4.1.3 and earlier, the default for mode is standard. dev - (Default) Use dev mode for development, testing, and demo purposes. It allows one instance of each subsystem to be created. standard - Use standard mode for production environments. It allows multiple instances of each subsystem to be created.
   apicup subsys set analyt ingress-type	Must be explicitly set to route for an OpenShift environment. For a standard K8s environment, ingress-type defaults to ingress and there is no need to explicitly enter this parameter.
   apicup certs set analyt CERT_NAME	[CERT_FILE KEY_FILE CA_FILE][flags] - Set the required certificates for the subsystem. Custom certificates may be set, otherwise, default certificates are automatically configured. For information on what certificates are available and how to set them see: Working with certificates.
   apicup subsys set analyt license-version <license_type>	<license_type> - Specify the type of license, either Production or Nonproduction. If not specified, the default value is Nonproduction. Note that the license type does not impact which Analytics image to install. The API Connect Kubernetes Pod annotations productID and productName reflect the selected license.
   apicup subsys install	analyt - Starts the installation of the analytic service

   Note: If a setting is not required for the ingestion-only configuration, you can omit it. A default value is supplied automatically by apicup but the value is ignored during installation. When you run the validation step, the value is not actually validated but is marked as valid in the results.

   Example 1: Installation commands for deployment that does not use the ingestion-only configuration.

   apicup subsys create analyt analytics --k8s
   apicup subsys set analyt extra-values-file=<path/file name>
   apicup subsys set analyt analytics-ingestion=<ai>.<hostname>.<domainname>
   apicup subsys set analyt analytics-client=<ac>.<hostname>.<domainname>
   apicup subsys set analyt registry=<registry-uri>
   apicup subsys set analyt namespace=<namespaceName>
   apicup subsys set analyt registry-secret=<registrySecret>
   apicup subsys set analyt coordinating-max-memory-gb=6
   apicup subsys set analyt data-max-memory-gb=6
   apicup subsys set analyt data-storage-size-gb=200
   apicup subsys set analyt master-max-memory-gb=6
   apicup subsys set analyt master-storage-size-gb=5
   apicup subsys set analyt enable-message-queue=<false>
   apicup subsys set analyt storage-class=<storageClass>
   apicup subsys set analyt es-storage-class=<es-storageClass>
   apicup subsys set analyt mq-storage-class=<mq-storageClass>
   apicup subsys set analyt mode=dev
   apicup subsys set analyt ingress-type=route <for OpenShift environments only>
   
   //Set the certificates 
   apicup certs set analyt CERT_NAME=[CERT_FILE KEY_FILE CA_FILE] [flags]
   
   // OPTIONAL: Write the plan to an output directory to inspect myProject/install-plan prior to installation
   apicup subsys install analyt --out=analyt-install-plan 
   // Start the installation from the output directory. Enter the full path to the output directory.
   apicup subsys install analyt --plan-dir=./myProject/analyt-install-plan
   
   //If output file is not used, enter the following command to start the installation
   apicup subsys install analyt
   

   Example 2: Installation commands for the ingestion-only configuration.

   apicup subsys create analyt analytics --k8s 
   apicup subsys set analyt extra-values-file=extra-values-analyt.yaml 
   apicup subsys set analyt ingestion-only=true 
   apicup subsys set analyt analytics-ingestion=<ai>.<hostname>.<domainname> 
   apicup subsys set analyt registry=<registry-uri> 
   apicup subsys set analyt namespace=<namespaceName> 
   apicup subsys set analyt registry-secret=<registrySecret> 
   apicup subsys set analyt enable-message-queue=<false> 
   apicup subsys set analyt storage-class=<storageClass> 
   apicup subsys set analyt mq-storage-class=<mq-storageClass> 
   apicup subsys set analyt mode=dev 
   apicup subsys set analyt ingress-type=route <for OpenShift environments only>
   apicup subsys set analyt storage-class=<storageClass> 
   apicup subsys set analyt mq-storage-class=<mq-storageClass>
   
   //Set the certificates 
   apicup certs set analyt CERT_NAME=[CERT_FILE KEY_FILE CA_FILE] [flags]
   
   // OPTIONAL: Write the plan to an output directory to inspect myProject/install-plan prior to installation
   apicup subsys install analyt --out=analyt-install-plan 
   
   // Start the installation from the output directory. Enter the full path to the output directory.
   apicup subsys install analyt --plan-dir=./myProject/analyt-install-plan
   
   //If output file is not used, enter the following command to start the installation
   apicup subsys install analyt
   

   An analytics installation starts the following Kubernetes pods:

   • Full installation in standard mode:

     Table 1. Kubernetes pods in a full Analytics installation

     Number	Pod
     2	client
     2	ingestion
     2	mtls
     1	operator
     3	storage-master
     3	storage-coordinating
     3	storage-data

     Note that in dev mode,there is only one of each pod.

   • Message queue deployment in standard mode: All of the pods shown in Table Table 1, plus:

     Table 2. Additional pods used for Message Queue deployments

     Number	Pod
     3	mq-kafka
     3	mq-zookeeper

     Note that in dev mode there is only one of each pod, with the same capability to enable or disable message queue.

   • Ingestion-only installation in standard mode:

     Table 3. Kubernetes pods in an ingestion-only Analytics installation

     Number	Pods
     2	ingestion
     2	mtls

     Note that in dev mode there is only one of each pod.

   Important: When the Analytics service is configured to store data, (that is, it is not configured for ingestion-only), the service depends on ElasticSearch which requires map counts higher than the operating system defaults. To change the map counts on the live system, run sudo sysctl -w vm.max_map_count=262144 on each Kubernetes node. To persist this change when node restarts occur, add the following to the /etc/sysctl.conf file: vm.max_map_count = 262144. This is the minimum recommended value. For more information see https://www.elastic.co/guide/en/elasticsearch/reference/current/vm-max-map-count.html

   Memory settings listed are maximum sizes. The Kubernetes memory resource request amount, or amount of memory reserved for each analytics pod, is 3/4 of the maximum memory. Actual memory used will usually be less than the reserved amount, but depends on current analytics load.

   Modifying allocation space after installation might not be possible depending on the type of persistent volume that is used.

2. After running the apicup subsys install command, run the apicup subsys get <analytics_subsys_name> --validate to validate the installation. You must correct any errors indicate by --validate prior to continuing. Following is an example for the --validate output for a configuration that does not use the ingestion-only feature:

   Kubernetes settings                                                                                      
   ===================                                                                                      
                                                                                                            
   Name                          Value                                                                       
   ----                          -----                                                                      
   extra-values-file                                                                                         ✔ 
   ingress-type                  ingress                                                                     ✔ 
   mode                          standard                                                                    ✔ 
   namespace                     prod                                                                        ✔ 
   registry                      docker-local.artifactory.swg-dev.com/apicup-imgs/2018.4.1-550               ✔ 
   registry-secret               apiconnect-image-pull-secret                                                ✔ 
   storage-class                 rook-block                                                                  ✔ 
                                                                                                            
                                                                                                            
   Subsystem settings                                                                                       
   ==================                                                                                       
                                                                                                            
   Name                          Value                                                                       
   ----                          -----                                                                      
   coordinating-max-memory-gb    6                                                                           ✔ 
   data-max-memory-gb            6                                                                           ✔ 
   data-storage-size-gb          200                                                                         ✔ 
   enable-message-queue          false                                                                       ✔ 
   es-storage-class              -                                                                           ✔ 
   master-max-memory-gb          6                                                                           ✔ 
   master-storage-size-gb        5                                                                           ✔ 
   mq-storage-class              -                                                                           ✔ 
                                                                                                            
                                                                                                            
   Endpoints                                                                                                
   =========                                                                                                
                                                                                                            
   Name                          Value                                                                       
   ----                          -----                                                                      
   analytics-client              ac.1.23.123.45.sample.io                                                     ✔ 
   analytics-ingestion           ai.1.23.123.45.sample.io                                                     ✔