Requirements for initial deployment on VMware

Review the requirements and considerations for deploying in a VMware environment.

Deployment requirements on VMware

  • Ensure you have supported software requirement versions. See IBM API Connect Version 2018 software product compatibility requirements

  • Do not change the hardware version of the OVA during installation. Do not attempt to use an unsupported version, even if VMWare indicates compatibility with other versions. For example, when deploying IBM API Connect, the VMWare UI for the APIC OVAs might show information like:

    Table 1.
    Property Value
    Guest OS Ubuntu Linux (64-bit)
    Compatibility ESXi 5.5 and later (VM version 10)
    VMware Tools Yes
    CPUs 4
    Memory 16 GB

    Although the Compatibility field shows ESXi 5.5 and later (VM version 10), API Connect supports only the versions listed in IBM API Connect Version 2018 software product compatibility requirements. Do not change the VM version of the OVA. Ensure that the Compatibility field values are not changed, and remain ESXi 5.5 and later (VM version 10).

    Attempts to modify the VMware compatibility may typically result in failure to boot the OVA, as per https://kb.vmware.com/s/article/52683.

  • Ensure that your operating system has one of the supported utilities for creating ISOs. The apicup installer uses mkisofs on Linux, and hdiutil on macOS. For Windows, you need software that creates ISO files using mkisofs, such as CDRTools. Verify that the utility you will use is located in a directory that is referenced by the PATH environment setting for your operating system. When creating the ISO, if you encounter the message Error: unable to create config ISO for host, verify that you have sufficient permissions to run the command.
  • Verify you have access to Passport Advantage® to download the Install Assist package and the latest IBM API Connect packages for your operating system.
    Package IBM API Connect subsystem file
    IBM API Connect® Management for VMWare apiconnect-management.ova
    IBM API Connect Analytics for VMware apiconnect-analytics.ova
    IBM API Connect Developer Portal for VMware apiconnect-portal.ova
    Important:

    Use a single APICUP project for all subsystems, even those in a different cluster. Multiple projects will result in multiple certificate chains which will not match.

    The original project directory created with APICUP during the initial product installation (for example, myProject) is required to both restore the database and to upgrade your deployment. You cannot restore the database or perform an upgrade without the initial project directory because it contains pertinent information about the cluster. Note that the endpoints and certificates cannot change; the same endpoints and certificates will be used in the restored or upgraded system. A good practice is to back up the original project directory to a location from where it can always be retrieved.

  • For each subsystem, gather the following networking settings, which you will need to supply during configuration:
    Table 2.
    Required information Value for your system
    IP address of the server  
    IP address of the server  
    Domain of the server  
    IP addresses of the name servers  
    IP address of the network gateway (not DataPower® gateway) for the server  
    Name of the Ethernet interface  
    VLAN  

    Some virtualization environments require additional information when you create and configure virtual machines. For example, it might be necessary to assign a specific VLAN ID, Resource Pool, or Datastore. Please refer to information provided by your virtualization environment administrators.

Configuration on VMware

  • API Connect cannot be deployed on NFS.
  • The timezone for API Connect pods is set to UTC. In API Connect deployments on VMware, the operating system timezone is also set to UTC. Do not change the timezone for the pods or the operating system.

  • Ensure that the time settings match (within a few seconds) between the machine running apicup and the VMware Host clock. To verify the VMware host clock setting, see https://kb.vmware.com/s/article/1003736.

    If the clocks are too different, the installation can fail because of invalid certificates due to time discrepancies.

  • API Connect requires a dedicated IP range for deployment of the Kubernetes pod and Kubernetes service networks. These IP addresses cannot conflict with IP addresses used by other resources in your deployment, such as SMTP servers or user registries. The default values are 172.16.0.0/16 and 172.17.0.0/16, respectively. If a /16 subnet overlaps with existing IPs on the network, a CIDR as small as /22 is acceptable.

    If the default ranges conflict with other programs, you can modify the API Connect ranges during initial installation. Note that you cannot modify them once an appliance has been deployed. Follow the instructions for your subsystem if you want to modify either of the IP ranges.

  • Only static IP addresses that are specified during the apicup project configuration before the installation of the OVAs are supported.
  • Designated host names must have wildcard aliases or host aliases, which ensures that the different endpoints work together. For example, *.hostname.mycompany.com.
  • Kubernetes ingress limits the character set for DNS names to not support the underscore character "_". This means you cannot specify underscores in domain names that are used as endpoints. For example, my_domain.bar.com and my.domain_abc.com are not supported for <xxx>.<hostname>.<domainname>, and will cause an error. For example:
    Invalid value: "my_domain.bar.com": a DNS-1123 subdomain must consist of lowercase alphanumeric characters, '-' or '.', 
and must start and end with an alphanumeric character (e.g. 'example.com', regex used for validation is
 '[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*')
  • Note that you cannot change host names or DNS names on a running cluster.
  • Version 2018.4.1.0 only: Ensure that Reverse DNS lookup is configured for the host names and endpoints for each subsystem. Be sure that a ping of the subsystem host names and endpoints resolves to the corresponding IP address.
    nslookup <ip_address>
ping <*.hostname.example.com>
    Note: Reverse DNS lookup is not required for Version 2018.4.1.1 or later.
  • For the management subsystem, the installer sets a default value of 9GB for cassandra-max-memory-gb. The minimum value for this setting is 9GB. The following table compares values for memory allocation for the management database:
    Memory allocated to OVA node Recommended cassandra-max-memory-gb MAX_HEAP_SIZE (47% of cassandra-max-memory-gb value)
    16GB 9GB (default) 4331m
    32GB 16GB 7700m
    64GB 24GB 11550m
  • The allocation of memory by the JVM is more than just heap size, so where the previous table shows the maximum heap size can grow by up to 4331m, there is also more memory that can be requested by the JVM from the operating system. The ratio of 47% that is used in the table provides sufficient padding so that under normal conditions the JVM should not request more than 9GB in total from the operating system. If the JVM did request more memory than the ratio padding allows, the limit in place on the Kubernetes pod would lead Kubernetes to kill the process/container so that it can be restarted, as per the design of setting memory limits on pods in Kubernetes.
  • For Analytics, the installer specifies a default value of 16 GB for es-max-memory-gb. The minimum value for this setting is 12 GB.
  • Decide the mode to use for the installation.
    Table 3. Deployment modes
    Mode Description
    dev Development mode (dev) deploys a subsystem with the scale of one. Development mode is recommended for development, testing, and demonstration purposes. 
    apicup subsys set mgmt mode=dev

    Do not use dev mode for production environments. Development mode does not provide high availability.
    standard Standard mode (standard) deploys in high availability mode for a production environment.
    apicup subsys set mgmt mode=standard

    Usage:

    • Mode is set for each subsystem type: Management, Analytics, Developer Portal, and Gateway.
    • If you do not specify the mode, a default mode is applied, as follows:
      • Version 2018.4.1.4 and later: dev mode
      • Version 2018.4.1.3 and earlier: standard mode
    • Use of standard mode is supported only on installations with three or more nodes. Installations with less than three nodes must use dev mode. If you install in standard mode with only a single node, some pods can remain in a pending state. To avoid having pods remain pending, either install in dev mode or add additional nodes.
  • For additional considerations for configuring clusters, see Configuring API Connect subsystems in a cluster on VMware.
    Important: For best performance it is recommended that the network latency between any 2 nodes be as low as possible. Do not configure nodes from the same subystem cluster across multiple data centers with a high latency network. A high latency network is one that experiences more than 30ms latency between nodes. For more information, see the API Connect V2018 Whitepaper
  • Configure a remote server for logging. Follow these instructions: Configuring remote logging for a VMware deployment. Pods are terminated during an upgrade, and the logs will be lost if not stored remotely.

Passwords and certificates

  • When creating configuration files for use in generating an ISO image for VMware, ensure that your working directories are secure. The VMware configuration requires an ISO image that contains a plain text password to be used to unlock the VMware data disk. This means that the API Connect project configuration file apiconnect-up.yml, and the /user-data directory for each host, contain the passwords you specified. This configuration information is used to create the ISO image that you combine with the ..ova distribution files when deploying (unlocking) the VMware data disk.
  • You can use apicup to specify an ssh keyfile that contains a public certificate for using ssh to log in to a virtual machine. Logging in through ssh is preferred because it is more secure than password-based login.
  • Default certificates are generated for each subsystem by the apicup subsys install command. If certificates are not explicitly set using the apicup certs set command, then default certificates are automatically generated by apicup. The default certificates are self-signed, so they may not provide a level of trust suitable for external communication. See Working with certificates.

Setting and using a hashed default password

During configuration of the Management, Analytics, and Developer Portal subsystems, you create a password to use to log in to the management console for the first time. You must use a password hashing utility to hash the password. You then use apicup to assign this hashed password to the subsystem. These configuration steps ensure that the password in not stored in plain text on the data disk.

The syntax of the apicup command is:
apicup subsys set mgmt default-password='hashed_password'

Usage notes:

  • The default-password is for the apicadm user account on the Appliance.
  • The password for apicadm can be used only to log in through the VMware console. You cannot use it to ssh into the Appliance as an alternative to using the ssh-keyfiles. Interactive login for ssh is disabled.
  • The default-password value configured is only used during initial installation (first boot) of each virtual appliance. Changing the value, then regenerating the ISO, and attaching the new ISO to the virtual appliance does not change the apicadm password.
  • The default-password must be hashed. If it is plain text, you will not be able to log into the Appliance through the VMware console. When you use apicup to set or get default-password, apicup ensures that the hash type of the password is one of the following:
    • MD5
    • SHA1
    • SHA256
    • SHA512
    • BCRYPT
    • MD5-Crypt

  • When using apicup to set a default password for a subsystem, be aware of syntax differences between operating systems. Windows requires double-quotes. Linux and OSX require single quotes.

    Operating system Command syntax
    Linux or OSX 
    apicup subsys set mgmt default-password='hashed_password'
    Windows 
    apicup subsys set mgmt default-password="hashed_password"
  • You can use the passwd command (on the appliance) to change the apicadm password.
  • When using the VMware Remote console to login to the appliance, be aware that the keyboard layout is English. This can cause a problems with hashed passwords, if you created the ISO on a system with a different keyboard layout and you used special characters or symbols. Passwords are hashed when you set the password that you enter to log into your Management appliance for the first time, and when you create hosts.

DataPower Gateway for API Connect on VMware

  • The Management server and Gateway firmware versions must match, for example, API Connect 2018.4.1.3 and DataPower 2018.4.1.3.
  • Installation and configuration of DataPower Gateway on an appliance (physical or virtual) is completed after you install the API Connect subsystems. For the gateway service in a VMware environment, use the instructions in Deploying DataPower Gateway.