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 remainESXi 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, andhdiutil
on macOS. For Windows, you need software that creates ISO files usingmkisofs
, 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 messageError: 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 VMwareHost
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
andmy.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
- Version 2018.4.1.4 and later:
- Use of
standard
mode is supported only on installations with three or more nodes. Installations with less than three nodes must usedev
mode. If you install instandard
mode with only a single node, some pods can remain in a pending state. To avoid having pods remain pending, either install indev
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.
apicup
command
is:apicup subsys set mgmt default-password='hashed_password'
Usage notes:
- The
default-password
is for theapicadm
user account on the Appliance. - The password for
apicadm
can be used only to log in through the VMware console. You cannot use it tossh
into the Appliance as an alternative to using thessh-keyfiles
. Interactive login forssh
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 theapicadm
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 useapicup
to set or getdefault-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.