Requirements for initial deployment on VMware

Deployment requirements on VMware

• Ensure you have supported software requirement versions. See IBM API Connect Version 10 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 10 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.

• 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.

  Endpoints for the components cannot change between deployments. However, the endpoints for the VMware hosts can be modified for the new deployment.

• 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.

Disk space requirements

• For Version 10, the data disk requirement for the management server is 200 GB. The boot disk requires 100 GB, so a minimum of 300 GB is needed for the management subystem. You specify the data disk size in Deploying the management subsystem OVA file when you deploy the OVF template in the VMware vSphere Web Client.
• The Developer Portal disk requirements vary with usage scenarios. See Table 1.
• Before you install, review all the minimum hardware requirements listed on the Hardware tab in the Software Product on the Compatibility Reports for API Connect. Follow the instructions in IBM API Connect Version 10 software product compatibility requirements.

API Connect 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.

• Deploying multiple similar subsystems in a single namespace is not supported. For example, deploying two management subsystems, mgmt1, mgmt2 in a single namespace where apiconnect operator is installed.
• 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.
• Endpoints cannot contain the underscore character "_" or uppercase characters.
• Host names that are used to create endpoints cannot contain the underscore character "_" or uppercase letters.
• 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.
• 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 deployment-profile to use for the installation.

  Table 3. Deployment profiles

  deployment-profile	Description
  Development	Development (non-production) deployment-profile deploys a subsystem with the scale of one. Development deployment-profile is recommended for development, testing, and demonstration purposes. Values are specific to each subsystem. The development deployment-profile is not recommended for production environments because it does not provide high availability. apicup subsys set mgmt deployment-profile=n1xc4.m16
  Production	Production deployment-profile deploys in high availability deployment-profile for a production environment. Values are specific to each subsystem. For example, for the management subsystem: apicup subsys set mgmt deployment-profile=n3xc4.m16

  Use of production deployment-profile is supported only on installations with three or more nodes. Installations with less than three nodes must use a development deployment-profile. If you install in a production deployment-profile with only a single node, some pods can remain in a pending state. To avoid having pods remain pending, either install in development deployment-profile or add additional nodes.

  Note that a deployment-profile is set for each subsystem type: Management, Analytics, and Developer Portal.

• For additional considerations for configuring clusters, see Configuring API Connect subsystems in a cluster.
  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.
• 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-v10.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 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

• 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.
• Ensure that DataPower Gateway firmware version you plan to install is compatible with the API Connect Management server version.
  Note:

  For API Connect Version 10.x, DataPower and API Connect releases must be within one release of each other. For example, API Connect v10.0.n runs with DataPower Gateway 10.0.n, v10.0.n-1, or v10.0.n+1.

  However, before you install, best practice is to review the latest compatibility support for your version of API Connect. 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.