Tips and tricks for using APICUP

The APICUP installer in Install Assist contains built-in time saving functions.

Introduction

This section describes tips and techniques for working with the APICUP installation commands. The APICUP installer creates charts and secrets that are then managed by Helm.

Running Tiller with APICUP

To run Tiller in a namespace:
export TILLER_NAMESPACE=apic

Entering multiple settings per command

To configure multiple settings per command, enter a space between each setting and enter an equals sign (=) to configure the setting.

In the following examples, be sure to replace [spc] with an actual space.

You can set multiple database parameters on one line: 
apicup subsys set mgmt cassandra-max-memory-gb=9[spc]cassandra-cluster-size=3[spc]cassandra-volume-size-gb=16[spc]cassandra-backup-protocol=sftp
You can set all endpoints on one line:
apicup subsys set mgmt platform-api=my.platform.com[spc]api-manager-ui=my.apim.com[spc]cloud-admin-ui=my.cloud.com[spc]consumer-api=my.consumer.com

Entering multiple values

Separate multiple values for a key/value pair with commas.
apicup subsys set mgmt dns-servers=8.8.8.8,4.4.4.4 search-domains=a.com,b.com

Viewing the settings for a subsystem

To view the current values that are set for a subsystem, enter the following command: apicup subsys get <subsys_name>. For example: apicup subsys get mgmt outputs the current values for the subsystem named mgmt and provides a description of each value. is organized into Kubernetes settings and Subsystem settings. Following is an example of the output from the get command

Figure 1. Output for the get command
 
                                                             
Endpoints                                        
=========                                        
                                                 
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 
platform-api                                      FQDN of platform API endpoint 
                                                 
                                                 
Error: Subsystem validation failure. Run with --validate to see details

Validating the settings for a subsystem

The values set for a subsystem can be validated for syntax by entering the --validate option for the get command: apicup subsys get <subsys_name> --validate. For example: apicup subsys get mgmt --validate validates the current values for the subsystem named mgmt. In the following example of the output for the --validate option, the check mark indicates a valid setting. The x indicates an invalid setting with an error message provided.

Figure 2. Output for the --validate option 

                                                 
Endpoints                                        
=========                                        
                                                 
Name                               Value          
----                               -----         
api-manager-ui                                    ✘  api-manager-ui is not a valid hostname 
cloud-admin-ui                                    ✘  cloud-admin-ui is not a valid hostname 
consumer-api                                      ✘  consumer-api is not a valid hostname 
platform-api                                      ✘  platform-api is not a valid hostname

Output an installation plan

Using APICUP, you can generate an installation plan and confirm it is correct prior to running the installation. You can then install the subsystem from the plan.

To output an installation plan, enter the following command:

apicup subsys install SUBSYS --out=install-plan

where <install-plan> is the name of the directory where the installation plan will be stored.

In the example, a directory named install-plan is created in the project directory. The myProject/install-plan directory contains the configuration parameters for the subsystem.

To install the subsystem from the install-plan, enter the following command from the project directory:

apicup subsys install SUBSYS --plan-dir=<full-path-to-plan-directory>

where <full-path-to-plan-directory> is the full qualified path to the plan directory.

Following are general rules for installing from the installation plan:

  • Never edit the files in the output directory directly. Instead, if changes are needed, update the parameters using APICUP and generate a new plan.
  • Always run APICUP commands from the original project directory created during the initial product installation. The project directory contains the apiconnect-up.yml file.
  • You can generate the plan in any location, but the install command must be run from the project directory. Enter the full path to the plan as the argument to --plan-dir to perform an installation.
The plan must be current with the project and the certificates. If the plan is older than the last modification date of the project or certificates, you will receive an error message such as:
the project was modified since the plan was generated, regenerate plan or skip this check 
with a --skip-health-check flag in the command
or
the certs were changed since the plan was generated, regenerate plan or skip this check with
 a --skip-health-check flag in the command

Getting help for commands

You can get help for all commands by entering: apicup --help. Following is an example of the output:

Figure 3. Help for Install Assist apicup commands

APIConnect Install Assist
Usage:
  apicup [command]

Available Commands:
  certs           Subsystem certificates
  completion      Generates bash or zsh completion scripts
  help            Help about any command
  hosts           Commands to configure subsystem hosts
  iface           Commands to configure hosts interfaces
  init            Create a new APIConnect UP project
  registry-upload Retag and upload images to custom registry
  server          Starts the APIConnect cluster operator
  subsys          Subsystem commands
  version         Get the APIConnect UP version

Flags:
      --accept-license   Accept the license for API Connect
      --debug            Enable debug logging
  -h, --help             help for apicup

Use "apicup [command] --help" for more information about a command.

Getting help on a specific command

For help on a specific command, enter --help after the command. For example, apicup subsys get mgmt --help prints out the usage and flags for the get command. For example:

Figure 4. Help for get command

Get subsystem properties

Usage:
  apicup subsys get SUBSYS [flags]

Flags:
      --endpoints   List endpoints (default true)
  -h, --help        help for get
      --platform    List platform settings (default true)
      --subsystem   List subsystem settings (default true)
      --validate    Validate settings

Global Flags:
      --accept-license   Accept the license for API Connect
      --debug            Enable debug logging