VMware deployment overview and requirements

Overview of an API Connect deployment on VMware

In a VMware deployment, your API Connect VMs are also referred to as appliances.

The API Connect software runs in docker containers that are managed in a Kubernetes environment that runs on the API Connect VMs. Most of the configuration of an API Connect VMware deployment is done in the project directory and the API Connect UIs, but some operations must be done inside the API Connect VMs, at the Kubernetes level.

Deployment requirements on VMware

• Review the compatibility requirements IBM API Connect Version 10 software product compatibility requirements
  Attention: API Connect is not supported on a FIPS-enabled environment.
• API Connect VMs require a CPU architecture that supports x86-64-v2.

• 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 you deploy API Connect, the VMware UI 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 that are listed in IBM API Connect Version 10 software product compatibility requirements. Do not change the VM version of the OVA. The compatibility field value must remain at ESXi 5.5 and later (VM version 10).

  Attempts to modify the VMware compatibility might result in failure to boot the OVA, see https://kb.vmware.com/s/article/52683.

• For each subsystem VM, gather the following networking settings, which you must supply during initial configuration:

  Table 2.

  Network setting	Value for your system
  IP address of the VM.
  Domain of the VM.
  IP addresses of the name servers (at least one DNS server is required).
  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. Refer to information provided by your virtualization environment administrators.

Before you deploy your API Connect subsystem OVA files, you first define some API Connect configuration properties and create ISO files that contain these properties. The ISO files are used to provide the initial configuration to the API Connect subsystems when your deploy the OVA files.

Disk space requirements

For the management subsystem, the data disk requirement is 200 GB. The boot disk requires 100 GB, so the total minimum requirement is 300 GB.

Key points for API Connect on VMware

• API Connect cannot be deployed on NFS.

• The time zone for API Connect VMs is set to Coordinated Universal Time. Do not change the time zone of your VMs.

• The time (not the time zone) on your project directory system and your VMware Host clock must match (within a few seconds).

  To verify the VMware host clock configuration, see https://kb.vmware.com/s/article/1003736. If a large time discrepancy exists between them, then the installation can fail due to invalid certificates.

• The API Connect VMs run a Kubernetes cluster that requires a dedicated IP range. 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. If a /16 subnet overlaps with existing IPs on the network, a CIDR as small as /22 is acceptable.

  You cannot modify the IP ranges after installation.

• Only static IP addresses are supported. You cannot change IP addresses after installation.

• API Connect VM hostnames and endpoints must be all lowercase, and not contain any special characters except for "-".

  You cannot change hostnames or endpoints after installation. If you want to change the endpoints, then you must reinstall API Connect and follow the form factor migration steps.

• If you are installing with three replica deployment profiles, do not split the replicas (VMs) across multiple data centers, unless network latency between data centers is less than 10 ms. For more information about multiple data center deployment options, see Multiple data center deployment strategies.

Passwords and certificates

• Ensure that your project directory is secure. The apiconnect-up-v10.yml file in the project directory contains hashed and base64 encoded passwords.
• During initial configuration, you use the apicup command to specify an ssh keyfile that contains a public certificate for using ssh to log in to your API Connect VMs. Logging in with ssh key files is preferred because it is more secure than password-based login.
• Default certificates are generated for each subsystem unless certificates are explicitly set before deployment (using the apicup certs set command). See API Connect TLS certificate best practices.

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 VMs 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 is not stored in plain text on the VMs data disk.

apicup subsys set mgmt default-password='hashed_password'

Usage notes:

• The default-password is for the apicadm user account on the VM.
• The password for apicadm can be used only to log in through the VMware console. You cannot use it to ssh into the VM 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 VM 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 VM 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 macOS require single quotes.

  Operating system	Command syntax
  Linux or macOS	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 VM) to change the apicadm password.
• When using the VMware remote console to login to the appliance, be aware that the keyboard layout is US 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.

DataPower Gateway for API Connect on VMware

• Installation and configuration of DataPower Gateway on an appliance (physical or virtual) is completed after you install the management, analytics, and portal subsystems. For the gateway service in a VMware environment, use the instructions in Deploying DataPower Gateway virtual appliance.
• Ensure that DataPower Gateway firmware version you plan to install is compatible with the API Connect management subsystem version. To view compatibility support, follow the instructions in IBM API Connect Version 10 software product compatibility requirements to access API Connect information on the Software Product Compatibility Reports website. Once you access information for your version of API Connect, select Supported Software > Integration Middleware, and view the list of compatible DataPower Gateway versions.