Preparing the management subsystem for deployment

Specify configuration properties for your management subsystem, and create the deployment ISO file.

Before you begin

Review the Deployment requirements on VMware.

Complete the Preparing to install API Connect in VMware.

Procedure

Change to the project directory.
```
cd <project directory>
```

Create your initial management subsystem definition.

apicup subsys create <subsystem name> management

Where <subsystem name> is the name you give the management subsystem that you are creating. The name must consist of lowercase alphanumeric characters or '-', contain no spaces, and starts and end with an a-z character.

Verify that the new subsystem is created, and has empty or default properties set:

apicup subsys get <subsystem name>

The following output is returned:

Appliance settings                                    
==================                                    
                                                      
Name                                   Value           Description 
----                                   -----           ------
additional-cloud-init-file                             (Optional) Path to additional cloud-init yml file 
...
<list of settings continues>

Specify the deployment profile for the subsystem, for example n1xc4.m16. The available profiles are described here: Planning your deployment topology and profiles.
```
apicup subsys set <subsystem name> deployment-profile=<profile>
```
Note: The deployment profiles that are shown in the Description column of the apicup get output might not be correct. The available profiles are documented in Planning your deployment topology and profiles.
Specify the API Connect license type.
```
apicup subsys set <subsystem name> license-use=<license type>
```
The license_type must be either production or nonproduction. If not specified, the default value is nonproduction.
Optional: Configure scheduled backups for your management database.

You can configure management database scheduled backups before or after installation. If you want to configure this now, follow step 1 of Configuring management database backups.
Optional: Configure your logging.
Logging can be configured after installation, but if you want to capture log events during installation then you must enable it before.
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 <subsystem name> additional-cloud-init-file=config_file.yml
```
Set your search domain. If you have multiple search domains, then use commas to separate them.
```
apicup subsys set <subsystem name> search-domain=<your search domain>
```
where <your search domain> is the domain for your VMs (use lowercase). For example: myorganization.com. Do not use wildcard DNS.
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 <subsystem name> dns-servers=ip_address_of_dns_server[,ip_address_of_another_dns_server_if_necessary]
```

Set your management subsystem endpoints.

Table 1. Management subsystem endpoints
Setting	Endpoint host description
`platform-api`	Platform API endpoint. The host where your platform API calls are routed. `apicup subsys set <subsystem name> platform-api=platform-api.hostname.domain`
`consumer-api`	Consumer API endpoint. The host where your consumer API calls are routed. `apicup subsys set <subsystem name> consumer-api=consumer-api.hostname.domain`
`cloud-admin-ui`	Cloud Manager user interface API endpoint. The host where your cloud administrator user-interface API calls are routed. `apicup subsys set <subsystem name> cloud-admin-ui=cloud-admin-ui.hostname.domain`
`api-manager-ui`	API Manager user interface endpoint. The host where your API Manager API calls are routed. `apicup subsys set <subsystem name> api-manager-ui=api-manager-ui.hostname.domain`
hub	The core microservice components for the Automated API behavior testing capability. This is an optional component and can be left unset if not used. `apicup subsys set <subsystem name> hub hub.hostname.domain` Note: Automated API behavior testing is not supported in two data center disaster recovery configurations.

Set the SSH public key to enable SSH public key authentication.
Specify the path to your SSH public key to enable SSH public key authentication. You can specify multiple paths by using commas as the separator.
```
apicup subsys set <subsystem name> ssh-keyfiles=<path to publicc ssh keyfile>
```
The public key is required so that the API Connect administrator can log in to the API Connect VMs with SSH. If you have multiple API Connect administrators, then include the public key for each administrator when you set ssh-keyfiles.

The default public key is typically located in the user's home directory, for example: <home directory>/.ssh/id_rsa.pub.

Set the VM console password.

Important: Review the requirements for creating a hashed password. See Setting and using a hashed default password.

Check that you have a password hashing tool installed.

Operating system	Command
Linux, macOS	If the mkpasswd command utility is not available, download and install it. (You can also use a different password hashing utility.) On macOS, use the command: `gem install mkpasswd`.
Windows, Red Hat	Use OpenSSL.

Create a hashed password.

Operating system	Command
Ubuntu, Debian, macOS	`mkpasswd --method=sha-512 --rounds=4096 password`
Windows, Red Hat	For example, with OpenSSL: `openssl passwd -1 password`. You might need to add your password hashing utility to your path; for example on Windows: `set PATH=c:\cygwin64\bin;%PATH%`

Set the hashed password for your subsystem:
```
apicup subsys set <subsystem name> default-password='<hashed password>'
```
- The password is hashed. If it is in plain text, you cannot log in to the VMware console.
- The password 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.
- On Linux or macOS, use single quotation marks around <hashed password>. For Windows, use double quotation marks.
- If you are not using a US English keyboard, understand the limitations with using the remote VMware console. See VMware deployment overview and requirements.

Optional: If the default IP ranges of 172.16.0.0/16 and 172.17.0.0/16 (which are used by Kubernetes on your API Connect VMs) conflict with IP addresses that are used by other processes in your deployment, then you can set a smaller CIDR.

A CIDR as small as /22 is supported.
You can modify the IP ranges during initial installation only. You cannot modify them after the API Connect VMs are deployed. See Key points for API Connect on VMware.
1. Update the IP range for the Kubernetes pods:
```
apicup subsys set <subsystem name> 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 <subsystem name> k8s-service-network='<new service range>'
```
  where <new service range> is the new value for the range.
Define the hostname for each subsystem VM that you are deploying. If you specified a one replica (n1) profile, then you are deploying one VM, so define one hostname. If you specified a three replica (n3) profile, then you are deploying three VMs so define three hostnames:
```
apicup hosts create <subsystem name> <hostname.domainname> <hd password>
```
where:
- <hostname.domainname> is the fully qualified name for the subsystem VM.
- <hd password> is the password that the Linux Unified Key Setup uses to encrypt the storage for your subsystem. This password is Base64 encoded when stored in your project directory, and is hashed in the ISO file and on the VM.
Repeat this command for each subsystem VM in your deployment. For example, if you are deploying a one replica profile then run the command once, for a three replica profile run the command three times (once for each <hostname.domainname>).
Define the network interfaces and IP configuration for your subsystem VMs.
```
apicup iface create <subsystem name> <hostname.domainname> <physical network id> <host ip address>/<subnet mask> <network gateway ip address>
```
where <physical network id> is the network interface ID of your VM. The value is usually ethx, where x is a number from 0 to 9.
Example:
```
apicup iface create <subsystem name> <myHostname.domain> eth0 192.0.2.10/255.255.255.0 192.0.2.1
```
For three replica deployments, repeat this command for each <myHostname.domain> in your subsystem deployment.

Note: The <network gateway ip address> is the network gateway (not a DataPower Gateway). If you are creating multiple network interfaces (on each VM), each one must be on a different subnet with a different gateway.

Optional: Use apicup to view the configured hosts:

apicup hosts list <subsystem name>
testsrv0231.subnet1.example.com
    Device  IP/Mask                     Gateway
    eth0    1.2.152.231/255.255.254.0  1.2.152.1

Note: This command might return the following messages, which you can ignore:

* host is missing traffic interface 
* host is missing public interface

Define your NTP server.

Note: If your environment has internet access, then ntp.ubuntu.com is used by default, and you can skip this step.
1. Create a file called cloud-init.yaml and paste in the details of your NTP server.
```
ntp:
  enabled: true
  ntp_client: systemd-timesyncd
  servers:
    - ntp.example.com
```
2. Set additional-cloud-init-file to your cloud-init.yaml file.
```
apicup subsys set <subsystem name> additional-cloud-init-file cloud-init.yaml
```
If you are installing a 2DCDR deployment, then follow the instructions in Installing a two data center deployment to configure your 2DCDR properties.

Verify that the configuration settings are valid.

apicup subsys get <subsystem name> --validate

The output shows all configuration settings, and has a checkmark against all settings that pass validation. If the setting does not have a checkmark, then it is invalid. See the following sample output.

Appliance settings                                                                                                                            
==================                                                                                                                            
                                                                                                                                              
Name                          Value                                                                                                            
----                          -----                                                                                                           
additional-cloud-init-file                                                                                                                     ✔ 
data-device                   sdb                                                                                                              ✔ 
default-password              $6$rounds=4096$vtcqpAVK$dzqrOeYP33WTvTug38Q4Rld5l8TmdQgezzTnkX/PFwkzTiZ2S0CqNRr1S4b08tOc4p.OEg4BtzBe/r8RAk.gW/   ✔ 
dns-servers                   [8.8.8.8]                                                                                                        ✔ 
extra-values-file                                                                                                                              ✔ 
k8s-pod-network               172.16.0.0/16                                                                                                    ✔ 
k8s-service-network           172.17.0.0/16                                                                                                    ✔ 
public-iface                  eth0                                                                                                             ✔ 
search-domain                 [subnet1.example.com]                                                                                            ✔ 
ssh-keyfiles                  [/home/vsphere/.ssh/id_rsa.pub]                                                                                  ✔ 
traffic-iface                 eth0                                                                                                             ✔ 
                                                                                                                                              
                                                                                                                                              
Subsystem settings                                                                                                                            
==================                                                                                                                            
                                                                                                                                              
Name                          Value                                                                                                            
----                          -----                                                                                                           
deployment-profile            n1xc4.m16                                                                                                        ✔ 
license-use                   production                                                                                                       ✔ 
multi-site-ha-enabled         false                                                                                                            ✔ 
multi-site-ha-mode            active                                                                                                           ✔ 
replication-peer-fqdn                                                                                                                          ✔ 
site-name                                                                                                                                      ✔ 
test-and-monitor-enabled      false                                                                                                            ✔ 
                                                                                                                                              
                                                                                                                                              
Endpoints                                                                                                                                     
=========                                                                                                                                     
                                                                                                                                              
Name                          Value                                                                                                            
----                          -----                                                                                                           
api-manager-ui                api-manager-ui.testsrv0231.subnet1.example.com                                                                   ✔ 
cloud-admin-ui                cloud-admin-ui.testsrv0231.subnet1.example.com                                                                   ✔ 
consumer-api                  consumer-api.testsrv0231.subnet1.example.com                                                                     ✔ 
hub                                                                                                                                            ✔ 
management-replication                                                                                                                         ✔ 
platform-api                  platform-api.testsrv0231.subnet1.example.com                                                                     ✔

Create your ISO files.
```
apicup subsys install <subsystem name> --out <subsystem name>plan-out
```
The ISO files are created in the <project directory>/<subsystem name>plan-out directory.

If the system cannot find your ISO file creation tool, then add it to your PATH property:
Operating system Command
Linux, macOS
export PATH=$PATH:/Users/your_path/

Windows
set PATH="c:\Program Files (x86)\cdrtools";%PATH%

Operating system	Command
Linux, macOS	`export PATH=$PATH:/Users/your_path/`
Windows	`set PATH="c:\Program Files (x86)\cdrtools";%PATH%`

What to do next

Use the ISO files to deploy your management OVA files. See Deploying the management subsystem OVA.