Configuring the management subsystem

Specify configuration properties for your management subystem, and create an ISO.

Before you begin

Review Deploying the Management subsystem

About this task

Use the apicup installation utility to specify configuration settings for your management subsystem.


  1. Ensure that you obtained the distribution file and have a project directory, as described in First steps for deploying in a VMware environment.
  2. Change to the project directory.
    cd myProject
  3. Create a management subsystem.
    apicup subsys create mgmt management
    • mgmt is the name of your management server that you are creating. You can assign it any name, as long as the identifier consists of lowercase alphanumeric characters or '-', with no spaces, starts with an alphabetic character, and ends with an alphanumeric character.
    • management indicates that you are creating a management microservice.

    The API Connect Helm charts are deployed into the default namespace. You do not need to specify a namespace.

    Tip: At any time, you can view the current management subsystem values in the apiconnect-up-v10.yml by running the apicup subsys get command:
    apicup subsys get mgmt
    If you have not yet configured the subsystem, the command might return errors. Also, if you have not updated the value, a default value is listed, if there is one that is available.

    After configuration is complete, you can view output similar to the following sample:

    Appliance settings                                                                                                                            
    Name                          Value                                                                                                            Description 
    ----                          -----                                                                                                            ------
    additional-cloud-init-file                                                                                                                     (Optional) Path to additional cloud-init yml file 
    data-device                   sdb                                                                                                              VM disk device (usually `sdb` for SCSI or `vdb` for VirtIO) 
    default-password              $6$rounds=4096$vtcqpAVK$dzqrOeYP33WTvTug38Q4Rld5l8TmdQgezzTnkX/PFwkzTiZ2S0CqNRr1S4b08tOc4p.OEg4BtzBe/r8RAk.gW/   (Optional) Console login password for `apicadm` user, password must be pre-hashed 
    dns-servers                   []                                                                                                        List of DNS servers 
    extra-values-file                                                                                                                              (Optional) Path to additional configuration yml file 
    k8s-pod-network                                                                                                         (Optional) CIDR for pods within the appliance 
    k8s-service-network                                                                                                     (Optional) CIDR for services within the appliance 
    public-iface                  eth0                                                                                                             Device for API/UI traffic (Eg: eth0) 
    search-domain                 []                                                                                            List for DNS search domains 
    ssh-keyfiles                  [/home/vsphere/.ssh/]                                                                                  List of SSH public keys files
    traffic-iface                 eth0                                                                                                             Device for cluster traffic (Eg: eth0) 
    Subsystem settings                                                                                                                            
    Name                          Value                                                                                                            Description 
    ----                          -----                                                                                                            ------
    deployment-profile            n1xc4.m16                                                                                                        Deployment profile (n1xc2.m16/n3xc4.m16) for analytics, (n1xc4.m16/n3xc4.m16) for management, (n1xc2.m8/n3xc4.m8) for portal 
    license-use                   production                                                                                                       License use (production/nonproduction) 
    multi-site-ha-enabled         false                                                                                                            Multi site HA enabled 
    multi-site-ha-mode            active                                                                                                           Multi site HA mode (active/passive) 
    replication-peer-fqdn                                                                                                                          Replication peer fully qualified name (replication endpoint of active mode site) 
    site-name                                                                                                                                      Site name, used in k8s resource names 
    test-and-monitor-enabled      false                                                                                                            Test and Monitor enabled 
    Name                          Value                                                                                                            Description 
    ----                          -----                                                                                                            ------
    api-manager-ui                                                                         FQDN of API manager UI endpoint 
    cloud-admin-ui                                                                         FQDN of Cloud admin endpoint 
    consumer-api                                                                             FQDN of consumer API endpoint 
    hub                                                                                                                                            FQDN of Test and Monitor hub endpoint, only required if Test and Monitor is enabled 
    management-replication                                                                                                                         FQDN of Management replication endpoint, only required if HA is enabled 
    platform-api                                                                             FQDN of platform API endpoint 
    turnstile                                                                                                                                      FQDN of Test and Monitor turnstile endpoint, only required if Test and Monitor is enabled
  4. For production environments, specify deployment-profile=n3xc4.m16.
    apicup subsys set mgmt deployment-profile=n3xc4.m16

    The deployment-profile=n3xc4.m16 parameter indicates that you are deploying in high availability (HA) mode for a production environment. The deployment-profile=n1xc4.m16 indicates a system for use in development and testing. For more information, see Requirements for initial deployment on VMware.

  5. Specify the license version you purchased.

    apicup subsys set mgmt license-use=<license_type>

    The license_type must be either production or nonproduction. If not specified, the default value is nonproduction.

  6. Optional: Configure backups of the subsystem. Note that once you set up scheduled backups, you can also run backups on-demand. Follow the instructions in Configure your Management subsystem backup.
    Important: It is highly recommend that you configure backups and also take additional steps to ensure that your configuration and data can be restored in the event of a disaster event. See Disaster recovery of the management subsystem on VMware.
  7. Optional: Configure your logging.
    Logging can be configured at a later time, but you must enable it before installation to capture the log events from the installation.
    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 mgmt additional-cloud-init-file=config_file.yml
  8. Enter the following commands to update the apiconnect-up-v10.yml with the information for your environment:
    1. Set your search domain. Multiple search domains should be separated by commas.
      apicup subsys set mgmt search-domain=your_search_domain

      Where your_search_domain is the domain of your servers, entered in all lowercase. Setting this value ensures that your searches also append these values, which are based on your company's DNS resolution, at the end of the search value. A sample search domain is

      Ensure that the value for your_search_domain is resolved in the system's /etc/resolv.conf file to avoid "502" errors when accessing the Cloud Manager web site. For example:

      # Generated by resolvconf
      search your_search_domain
    2. 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 mgmt dns-servers=ip_address_of_dns_server[,ip_address_of_another_dns_server_if_necessary]
      DNS entries may not be changed on a cluster after the initial installation.
    3. Use apicup to set your endpoints.
      You can use wildcard aliases or host aliases with your endpoints.

      Optionally, you can specify all endpoints with one apicup command.

      Note: You cannot specify the underscore character "_" in domain names that are used in endpoints. See API Connect configuration on VMware.
      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 mgmt platform-api=platform-api.hostname.domain
      consumer-api Consumer API endpoint. The host where your consumer API calls are routed.
      apicup subsys set mgmt consumer-api=consumer-api.hostname.domain
      cloud-admin-ui Cloud admin user interface API endpoint. The host where your cloud administrator user-interface API calls are routed.
      apicup subsys set mgmt 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 mgmt api-manager-ui=api-manager-ui.hostname.domain
      hub The core microservice components for the Automated API behavior testing capability.
      apicup subsys set mgmt hub hub.hostname.domain
      turnstile Allows for communication between the Test pods and the API Management subsystem.
      apicup subsys set mgmt turnstile turnstile.hostname.domain
  9. Set a Public key.
    apicup subsys set mgmt ssh-keyfiles=path_to_public_ssh_keyfile

    Setting this key enables you to use ssh with this key to log in to the virtual machine to check the status of the installation. You will perform this check in later in Deploying the management subsystem OVA file.

  10. Set the password that you enter to log into your Management appliance for the first time.
    1. Important: Review the requirements for creating and using a hashed password. See Setting and using a hashed default password.
    2. If you do not have a password hashing utility, install one.
      Operating system Command
      Ubuntu, Debian, OSX If the mkpasswd command utility is not available, download and install it. (You can also use a different password hashing utility.) On OSX, use the command: gem install mkpasswd .
      Windows, Red Hat If necessary, a password hashing utility for the Windows operating system, like OpenSSL
    3. Create a hashed password
      Operating system Command
      Ubuntu, Debian, OSX
      mkpasswd --method=sha-512 --rounds=4096 password
      Windows, Red Hat For example, using OpenSSL: openssl passwd -1 password. Note that you might need to add your password hashing utility to your path; for example, on Windows:
      set PATH=c:\cygwin64\bin;%PATH%
    4. Set the hashed password for your subsystem:
      apicup subsys set mgmt default-password='hashed_password'
  11. Optional: If the default IP ranges for the API Connect Kubernetes pod and the service networks conflict with IP addresses that must be used by other processes in your deployment, modify the API Connect values.
    You can change the IP ranges of the Kubernetes pod and the service networks from the default values of and, respectively. In the case that a /16 subnet overlaps with existing IPs on the network, a Classless Inter-Domain Routing (CIDR) as small as /22 is acceptable. You can modify these ranges during initial installation and configuration only. You cannot modify them once an appliance has been deployed. See API Connect configuration on VMware.
    1. Update the IP range for the Kubernetes pod
      apicup subsys set mgmt 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 mgmt k8s-service-network='new_service_range'

      Where new_service _range is the new value for the range.

  12. Add your hosts.
    apicup hosts create mgmt hostname.domainname hd_password
    Where the following are true:
    • hostname.domainname is the fully qualified name of the server where you are hosting your Management service, including the domain information.
    • hd_password is the password that the Linux Unified Key Setup uses to encrypt the storage for your Management service. This password is hashed when it is stored on the server or in the ISO. Note that the password is base64 encoded when stored in apiconnect-up-v10.yml.

    Repeat this command for each host that you want to add.

    Note: Host names and DNS entries may not be changed on a cluster after the initial installation.
  13. Create your interfaces.
    apicup iface create mgmt 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 physical server. The value is most often eth0. The value can also be ethx, where x is a number identifier.

    The format is similar to this example: apicup iface create mgmt myHostname.domain eth0

    Note: The network_gateway_ip_address is the network gateway (not a DataPower Gateway). If you are creating multiple network interfaces, each one must be on a different subnet with a different gateway.
  14. Optional: Use apicup to view the configured hosts:
    apicup hosts list mgmt
        Device  IP/Mask                     Gateway
    Note: This command might return the following messages, which you can ignore:
    * host is missing traffic interface 
    * host is missing public interface 

    Note: If you are configuring two data center deployment, continue with the installation instructions in Installing a two data center deployment.

  15. Optional: Verify that the configuration settings are valid.
    apicup subsys get mgmt --validate

    The output lists each setting and adds a check mark after the value once the value is validated. If the setting lacks a check mark and indicates an invalid value, reconfigure the setting. 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                   []                                                                                                        ✔ 
    extra-values-file                                                                                                                              ✔ 
    k8s-pod-network                                                                                                         ✔ 
    k8s-service-network                                                                                                     ✔ 
    public-iface                  eth0                                                                                                             ✔ 
    search-domain                 []                                                                                            ✔ 
    ssh-keyfiles                  [/home/vsphere/.ssh/]                                                                                  ✔ 
    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                                                                                                            ✔ 
    Name                          Value                                                                                                            
    ----                          -----                                                                                                           
    api-manager-ui                                                                         ✔ 
    cloud-admin-ui                                                                         ✔ 
    consumer-api                                                                             ✔ 
    hub                                                                                                                                            ✔ 
    management-replication                                                                                                                         ✔ 
    platform-api                                                                             ✔ 
    turnstile                                                                                                                                      ✔ 
  16. Create your ISO file.
    apicup subsys install mgmt --out mgmtplan-out

    The --out parameter and value are required.

    In this example, the ISO file is created in the myProject/mgmtplan-out directory.

    If the system cannot find the path to your software that creates ISO files, create a path setting to that software by running a command similar to the following command:

    Operating system Command
    OSX and Linux
    export PATH=$PATH:/Users/your_path/
    set PATH="c:\Program Files (x86)\cdrtools";%PATH%
  17. Deploy the subsystem ISO. Continue with Deploying the management subsystem OVA file.