Configuring the Developer Portal subsystem

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

Before you begin

Review the requirements and important deployment information for Developer Portal. See Deploying the Developer Portal virtual appliance.

About this task

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

Procedure

  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 portal subsystem.
    apicup subsys create port portal
    Where:
    • port is the name of the Developer Portal 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.
    • portal indicates that you want it to create a Developer Portal microservice.
    Note: Unless you are installing a two data center deployment, leave multi-site-ha-enabled as false, and ignore multi-site-ha-mode, replication-peer-fqdn, site-name, and the portal-replication endpoint, as these options are all related to that feature. For more information, see Installing a two data center deployment on VMware.
    The apiconnect-up-v10.yml file that is in that directory is updated to add the portal-related entries.
    Tip: At any time, you can view the current developer portal subsystem values in the apiconnect-up-v10.yml by running the apicup get command:
    apicup subsys get port
    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                   [192.168.1.201]                                                                                                  List of DNS servers 
    extra-values-file                                                                                                                              (Optional) Path to additional configuration yml file 
    k8s-pod-network               172.16.0.0/16                                                                                                    (Optional) CIDR for pods within the appliance 
    k8s-service-network           172.17.0.0/16                                                                                                    (Optional) CIDR for services within the appliance 
    public-iface                  eth0                                                                                                             Device for API/UI traffic (Eg: eth0) 
    search-domain                 [subnet1.example.com]                                                                                            List for DNS search domains 
    ssh-keyfiles                  [/home/vsphere/.ssh/id_rsa.pub]                                                                                  List of SSH public keys files 
    traffic-iface                 eth0                                                                                                             Device for cluster traffic (Eg: eth0) 
                                                                                                                                                  
                                                                                                                                                  
    Subsystem settings                                                                                                                            
    ==================                                                                                                                            
                                                                                                                                                  
    Name                          Value                                                                                                            Description 
    ----                          -----                                                                                                            ------
    deployment-profile            n1xc2.m8                                                                                                         Deployment profile (n1xc2.m16/n3xc4.m16) for analytics, (n1xc4.m16/n3xc4.m16) for management, (n1xc2.m8/n3xc4.m8) for portal 
    license-use                   nonproduction                                                                                                    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 
                                                                                                                                                  
                                                                                                                                                  
    Endpoints                                                                                                                                     
    =========                                                                                                                                     
                                                                                                                                                  
    Name                          Value                                                                                                            Description 
    ----                          -----                                                                                                            ------
    portal-admin                  portal-api.example.com                                                                                           FQDN of Portal admin endpoint 
    portal-replication                                                                                                                             FQDN of Portal replication endpoint, only required if HA is enabled 
    portal-www                    portal-www.example.com                                                                                           FQDN of Portal web endpoint 
    
  4. Specify deployment-profile.
    apicup subsys set port deployment-profile=n3xc4.m8

    The deployment-profile parameter indicates that you are deploying a three replica or one replica environment. For more information, see Planning your deployment topology and profiles.

    Note: The deployment profiles that are shown in the Description column of the apicup get output are not correct. The available profiles are documented in Planning your deployment topology and profiles.
  5. Specify the license version you purchased.

    apicup subsys set port license-use=<license_type>

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

  6. Optional: Configure scheduled backups of the subsystem. This step is optional but is recommended.

    Refer to the instructions in Backing up and restoring the Developer Portal.

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

      The endpoints must be unique hostnames which both point to the IP address of the OVA (single node deployment), or to the IP of a load balancer configured in front of the OVA nodes. See examples in the sample output in step 3.

      Setting Endpoint host description
      portal-admin This is the unique_hostname for communication between your Cloud Manager and API Manager, and your Developer Portal. The values for the portal-admin and portal-www must be different.
      apicup subsys set port portal-admin=unique_hostname.domain
      portal-www This is the unique_hostname for the Developer Portal Internet site that is created for the Developer Portal. Multiple portal-www endpoints may be configured, as described here: Defining multiple portal endpoints for a VMware environment.
      apicup subsys set port portal-www=unique_hostname.domain
    2. Set your search domain. Multiple search domains should be separated by commas.
      apicup subsys set port 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 mycompany.example.com.

      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 ibm.com other.domain.com
    3. 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 port 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.
  9. Set a Public key.
    apicup subsys set port 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 Verifying deployment of the Developer Portal subsystem.

  10. If there are multiple Management subsystems in the same project, set the Portal subsystem's platform-api and consumer-api certificates to match those used by the appropriate Management subsystem to ensure that the Portal subsystem is correctly associated with that Management subsystem.

    This step only applies if you installed more than one Management subsystem into a single project.

    A Portal subsystem can be associated with only one Management subsystem. To associate the new Portal subsystem with the appropriate Management subsystem, manually set the mgmt-platform-api and mgmt-consumer-api certificates to match the ones used by the Management subsystem.

    1. Run the following commands to get the certificates from the Management subsystem:
      apicup certs get mgmt-subsystem-name platform-api -t cert > platform-api.crt
      apicup certs get mgmt-subsystem-name platform-api -t key > platform-api.key
      apicup certs get mgmt-subsystem-name platform-api -t ca > platform-api-ca.crt
      
      apicup certs get mgmt-subsystem-name consumer-api -t cert > consumer-api.crt
      apicup certs get mgmt-subsystem-name consumer-api -t key > consumer-api.key
      apicup certs get mgmt-subsystem-name consumer-api -t ca > consumer-api-ca.crt

      where mgmt-subsystem-name is the name of the specific Management subsystem that you want to associate the new Portal subsystem with.

    2. Run the following commands to set the Portal's certificates to match those used by the Management subsystem:
      apicup certs set ptl-subsystem-name mgmt-platform-api Cert_file_path Key_file_path CA_file_path
      
      apicup certs set ptl-subsystem-name mgmt-consumer-api Cert_file_path Key_file_path CA_file_path

      For more information on apicup certificate commands, see Command reference.

  11. You can set a hashed password that you enter to log in to your Developer Portal server 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 port default-password="hashed_password"

    Notes:

    • The password is hashed. If it is in plain text, you cannot log into the VMWare console.
    • Note that the password can only be used to login through the VMware console. You cannot use it to SSH into the Appliance as an alternative to using the ssh-keyfiles.
    • On Linux or OSX, use single quotes around hashed_password. For Windows, use double quotes.
    • If you are using a non-English keyboard, understand the limitations with using the remote VMware console. See Requirements for initial deployment on VMware.
  12. 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 172.16.0.0/16 and 172.17.0.0/16, 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 port 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 port k8s-service-network='new_service_range'

      Where new_service _range is the new value for the range.

  13. Add your hosts.
    apicup hosts create port hostname.domainname hd_password
    Where the following are true:
    • hostname.domainname is the fully qualified name of the server where you are hosting your Developer Portal, including the domain information.
    • hd_password is the password of the Linux Unified Key Setup uses to encrypt the storage for your Developer Portal. 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.
  14. Create your interfaces.
    apicup iface create port hostname.domainname physical_network_id host_ip_address/subnet_mask 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 port myHostname.domain eth0 192.0.2.1/255.255.1.1 192.0.2.1

    Note: You can optionally configure a second network interface (NIC) card for use with Developer Portal. In this scenario, one NIC is used for internal traffic between the Portal and APIM, and the second is used as a public interface. If you are creating multiple network interfaces, each one must be on a different subnet with a different gateway. For information on configuring two NICs for Developer Portal, see Configuring two NICs on the Developer Portal.
  15. Optional: You can specify a range of allowable client IP addresses.

    You can optionally restrict which IP addresses can access any of the ingresses by creating an allowlist annotation, which then will only allow the specified IP addresses to access the ingress and will deny all other source IP addresses. See Specifying a range of allowable client IP addresses for Developer Portal.

    Note: One usage of this restriction is the scenario where you split traffic between your private and public networks in 2 NIC configuration.
  16. Optional: Use apicup to view the configured hosts:
    apicup hosts list port
    apimdev0232.hursley.ibm.com
     Device  IP/Mask                     Gateway
     eth0    1.2.152.232/255.255.254.0   1.2.152.1

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

  17. Optional: Enable JWT security instead of mTLS for communication from management to your portal subsystem.
    JWT security provides application layer security and can be used instead of mTLS when there are load-balancers located between subsystems that require TLS termination. For more information about JWT security, see Enable JWT instead of mTLS. To enable JWT and disable mTLS, first identify the JWKS URL from the management subsystem:
    apicup subsys get <management subsystem>
    
    ...
    jwks-url     https://appliance1.apic.acme.com/api/cloud/oauth2/certs  JWKS URL for Portal and Analytics subsystems to validate JWT -- this is unsettable and is generated based on the platform-api endpoint 
    ...
    Disable mTLS and enable JWT by setting the jwks-url with apicup:
    apicup subsys set port mtls-validate-client=false
    apicup subsys set port jwks-url=https://appliance1.apic.acme.com/api/cloud/oauth2/certs
    Note: Do not disable mTLS without enabling JWT.
  18. Leave multi-site-ha-enabled set to false.
  19. Optional: Verify that the configuration settings are valid.
    apicup subsys get port --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                   [192.168.1.201]                                                                                                  ✔ 
    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            n1xc2.m8                                                                                                         ✔ 
    license-use                   nonproduction                                                                                                    ✔ 
    multi-site-ha-enabled         false                                                                                                            ✔ 
    multi-site-ha-mode            active                                                                                                           ✔ 
    replication-peer-fqdn                                                                                                                          ✔ 
    site-name                                                                                                                                      ✔ 
                                                                                                                                                  
                                                                                                                                                  
    Endpoints                                                                                                                                     
    =========                                                                                                                                     
                                                                                                                                                  
    Name                          Value                                                                                                            
    ----                          -----                                                                                                           
    portal-admin                  portal-api.example.com                                                                                           ✔ 
    portal-replication                                                                                                                             ✔ 
    portal-www                    portal-www.example.com                                                                                           ✔ 
    
    
  20. Create your ISO file.
    apicup subsys install port --out portplan-out

    The --out parameter and value are required. In this example, the ISO file is created in the myProject/portplan-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
    Ubuntu, Debian, OSX
    export PATH=$PATH:/Users/your_path/
    Windows, Red Hat
    set PATH="c:\Program Files (x86)\cdrtools";%PATH%
  21. Next, use the ISO to deploy the subsystem OVA. Continue with Deploying the Developer Portal subsystem OVA file.