Configuring the Analytics subsystem

Specify configuration properties for your Analytics subsystem, and create an ISO.

Before you begin

Review the requirements. See Deploying the Analytics subsystem.

About this task

Use the apicup installation utility to specify configuration settings for your Analytics subsystem.


  1. Ensure that you obtained the distribution file and have a project directory, as described in First steps for deploying in a VMware environment.
  2. Change to the project directory.
    cd myProject
  3. Create an analytics subsystem.
    apicup subsys create analyt analytics
    • analyt is the name of the analytics server that you are creating. You can assign it any name, as long as the identifier consists of lowercase alphanumeric characters or '-', with no spaces, starts with an alphabetic character, and ends with an alphanumeric character.
    • analytics indicates that you want it to create an Analytics microservice.
    The apiconnect-up.yml file that is in that directory is updated to add the analytics-related entries.
    Tip: At any time, you can view the current analytics subsystem values in the apiconnect-up.yml by running the apicup get command:
    apicup subsys get analyt
    If you have not updated the value, a default value is listed, if there is one that is available.

    Sample output from apicup subsys get, after configuration is completed:

     apicup subsys get analyt
    Appliance settings
    Name                          Value                                               Description
    ----                          -----                                               ------
    additional-cloud-init-file                                                       (Optional) Path to additional cloud-init yml file
    data-device                   sdb                                                VM disk device (usually `sdb` for SCSI or `vdb` for VirtIO)
    default-password              $6$rounds=4096$iMCJ9cfhFJ8X$pbmAl
                                  uE8uLD.9jwHE0AX4upFSqx/jf0ZmDbHPZ9bUlCY1           (Optional) Console login password for `apicadm` user
    dns-servers                   []                                       List of DNS servers
    k8s-pod-network                                           (Optional) CIDR for pods within the appliance
    k8s-service-network                                       (Optional) CIDR for services within the appliance
    deployment-profile            n3xc4.m16
    public-iface                  eth0                                               Device for API/UI traffic (Eg: eth0)
    search-domain                 []                              List for DNS search domains
    ssh-keyfiles                  [/home/vsphere/.ssh/]                    List of SSH public keys files
    traffic-iface                 eth0                                               Device for cluster traffic (Eg: eth0)
    license-use                   production
    Name                          Value                                              Description
    ----                          -----                                              ------
    analytics-client             FQDN of Analytics client/UI endpoint
    analytics-ingestion              FQDN of Analytics ingestion endpoint
  4. Specify your deployment-profile.
    apicup subsys set analyt deployment-profile=profile_type

    Use one of the following values for the profile_type, based on the decision you made while Planning the Analytics profile and storage:

    • For development use: n1xc2.m16
    • For production use: n3xc4.m16: production profile

    For example, to deploy using the a production profile, run the following command:

    apicup subsys set analyt deployment-profile=n3xc4.m16
  5. Specify the license use that you purchased.
    apicup subsys set analyt license-use=license_type

    The license_type must be either production or nonproduction. If not specified, the default value is nonproduction.

  6. Optional: Configure backups of the subsystem. Follow the instructions in Backing up and restoring the Analytics database on VMware.
    Important: It is highly recommend that you configure backups and also take additional steps to ensure that your configuration and data can be restored in the event of a disaster event. See Preparing the Analytics subsystem for disaster recovery on VMware.
  7. Optional: Enable the message queue microservice with the default values.
    If you did not previously enable message queue with custom settings, you can enable it now with the following default values:
    • storageClassName set to local-storage
    • volumeSize set to 5Gi
    1. List the settings of your Analytics subsystem by running the following command:
      apicup subsys get Analytics_subsystem_name

      Confirm that the enable-message-queue field is set to false (the message queue is not enabled by default).

    2. Enable the message queue by running the following command to set enable-message-queue to true:
      apicup subsys set Analytics_subsystem_name enable-message-queue=true
  8. Optional: Configure your logging.
    Logging can be configured at a later time, but you must enable it before installation to capture the log events from the installation.
    1. Complete the procedure at Configuring remote logging for a VMware deployment.
    2. Enter the following command to create the log file:
      apicup subsys set analyt additional-cloud-init-file=config_file.yml
  9. Enter the following commands to update the apiconnect-up.yml with the information for your environment:
    1. Use apicup to set your endpoints.

      The endpoints must be unique host names that both point to the IP address of the OVA (single node deployment), or to the IP of a load balancer configured in front of the OVA nodes.

      Setting Endpoint host description
      analytics-client Your unique_hostname identifies the endpoint that enables the Cloud Manager, API Manager, and Developer Portal to communicate with the Analytics subsystem.
      apicup subsys set analyt analytics-client=unique_hostname.domain

      If you plan to disable internal storage for Analytics data, omit this setting.

      analytics-ingestion Your unique_hostname identifies the endpoint that enables the Gateway to push your analytics data. The values for the analytics-ingestion and analytics-client must be different.
      apicup subsys set analyt analytics-ingestion=unique_hostname.domain
    2. Set your search domain. Multiple search domains should be separated by commas.
      apicup subsys set analyt search-domain=your_search_domain

      Where your_search_domain is the domain of your servers, entered in all lowercase. Setting this value ensures that your searches also append these values, which are based on your company's DNS resolution, at the end of the search value. A sample search domain is

      Ensure that the value for your_search_domain is resolved in the system's /etc/resolv.conf file to avoid "502" errors when accessing the Cloud Manager web site. For example:

      # Generated by resolvconf
      search your_search_domain
    3. Set your domain name servers (DNS).
      Supply the IP addresses of the DNS servers for your network. Use a comma to separate multiple server addresses.
      apicup subsys set analyt dns-servers=ip_address_of_dns_server
      DNS entries may not be changed on a cluster after the initial installation.
  10. Set a Public key.
    apicup subsys set analyt ssh-keyfiles=path_to_public_ssh_keyfile

    Setting this key enables you to use ssh with this key to log in to the virtual machine to check the status of the installation. You will perform this check later in Verifying deployment of the Analytics subsystem.

  11. You can set the password that you enter to log into your Analytics server for the first time.
    1. Review the requirements for creating and using a hashed password. See Setting and using a hashed default password.
    2. If you do not have a password hashing utility, install one.
      Operating system Command
      Ubuntu, Debian, OSX If the mkpasswd command utility is not available, download and install it. (You can also use a different password hashing utility.) On OSX, use the command: gem install mkpasswd .
      Windows, Red Hat If necessary, a password hashing utility for the Windows operating system, like OpenSSL
    3. Create a hashed password
      Operating system Command
      Ubuntu, Debian, OSX
      mkpasswd --method=sha-512 --rounds=4096 password
      Windows, Red Hat For example, using OpenSSL: openssl passwd -1 password. Note that you might need to add your password hashing utility to your path; for exaample, on Windows:
      set PATH=c:\cygwin64\bin;%PATH%
    4. Set the hashed password for your subsystem:
      apicup subsys set analyt default-password='hashed_password'


      • The password is hashed. If it is in plain text, you cannot log into the VMWare console.
      • Note that the password can only be used to login through the VMware console. You cannot use it to SSH into the Appliance as an alternative to using the ssh-keyfiles.
      • On Linux or OSX, use single quotes around hashed_password. For Windows, use double quotes.
      • If you are using a non-English keyboard, understand the limitations with using the remote VMware console. See Requirements for initial deployment on VMware.
  12. Optional: If the default IP ranges for the API Connect Kubernetes pod and the service networks conflict with IP addresses that must be used by other processes in your deployment, modify the API Connect values.
    You can change the IP ranges of the Kubernetes pod and the service networks from the default values of and, respectively. In the case that a /16 subnet overlaps with existing IPs on the network, a Classless Inter-Domain Routing (CIDR) as small as /22 is acceptable. You can modify these ranges during initial installation and configuration only. You cannot modify them once an appliance has been deployed. See API Connect configuration on VMware.
    1. Update the IP range for the Kubernetes pod
      apicup subsys set analyt k8s-pod-network='new_pod_range'

      Where new_pod_range is the new value for the range.

    2. Update the IP range for Service networks.
      apicup subsys set analyt k8s-service-network='new_service_range'

      Where new_service _range is the new value for the range.

  13. Add your hosts.
    apicup hosts create analyt hostname.domainname hd_password
    Where the following are true:
    • hostname.domainname is the fully qualified name of the server where you are hosting your Analytics service, including the domain information.
    • hd_password is the password of the Linux Unified Key Setup uses to encrypt the storage for your Analytics service. This password is hashed when it is stored on the server or in the ISO. Note that the password is base64 encoded when stored in apiconnect-up.yml.

    Repeat this command for each host that you want to add.

    Note: Host names and DNS entries may not be changed on a cluster after the initial installation.
  14. Create your interfaces.
    apicup iface create analyt hostname.domainname physical_network_id host_ip_address/subnet_mask gateway_ip_address
    Where physical_network_id is the network interface ID of your physical server. The value is most often eth0. The value can also be ethx, where x is a number identifier.
    The format is similar to this example: apicup iface create analyt myHostname.domain eth0
  15. Optional: Use apicup to view the configured hosts:
    apicup hosts list analyt
        Device  IP/Mask                     Gateway
  16. Verify that the configuration settings are valid.
    apicup subsys get analyt --validate

    The output lists each setting and adds a check mark after the value once the value is validated. If the setting lacks a check mark and indicates an invalid value, reconfigure the setting. See the following sample output.

     apicup subsys get analyt --validate
    Appliance settings
    Name                          Value
    ----                          -----
    additional-cloud-init-file                                                                                   ✔
    data-device                   sdb                                                                            ✔
    default-password              $6$rounds=4096$iMCJ9cfhFJ8X$pbmAl9ClWzcYzH
                                      ZFoQ6n7OnYCf/owQZIiCpAtWazs/FUn/uE8uLD.9jwHE0AX4upFSqx/jf0ZmDbHPZ9bUlCY1   ✔
    dns-servers                   []                                                                      ✔
    k8s-pod-network                                                                       ✔
    k8s-service-network                                                                   ✔
    deployment-profile            Prod                                                                       ✔
    public-iface                  eth0                                                                           ✔
    search-domain                 []                                                          ✔
    ssh-keyfiles                  [/home/vsphere/.ssh/]                                                ✔
    traffic-iface                 eth0                                                                           ✔
    license-version               Production
    Name                          Value
    ----                          -----
    analytics-client                                          ✔
    analytics-ingestion                                          ✔
  17. If you configured additional deployment options in an extra-values file, run the following command to make the file available during installation:
    apicup subsys set analyt extra-values-file path/analytics-extra-values.yaml

    where extra-values.yaml is the name of the file containing your deployment settings.

  18. Create your ISO file.
    apicup subsys install analyt --out analytplan-out

    The --out parameter and value are required. In this example, the ISO file is created in the myProject/analytplan-out/node-config directory.

    If the system cannot find the path to your software that creates ISO files, create a path setting to that software by running a command similar to the following command:

    Operating system Command
    Ubuntu, Debian, OSX
    export PATH=$PATH:/Users/your_path/
    Windows, Red Hat
    set PATH="c:\Program Files (x86)\cdrtools";%PATH%
  19. Next, use the ISO to deploy the OVA file. Continue with Deploying the Analytics subsystem OVA file.