Installing the Developer Portal subsystem into a Kubernetes environment

Use the Install Assist utility program to install the Developer Portal subsystem into your Kubernetes runtime environment.

Before you begin

Before installing the Portal subsystem, complete the steps that are described in First steps for installing API Connect: Upload files to registry. For instructions on using the APICUP installer, see Tips and tricks for using APICUP.

Tip: To enable effective high availability for your Portal service, you need a latency that is less than 50ms between all portal-db pods to avoid the risk of performance degradation. Servers with uniform specifications are required, as any write actions occur at the speed of the slowest portal-db pod, as the write actions are synchronous across the cluster of portal-db pods. It is recommended that there are three servers in each cluster of portal-db pods for the high availability configuration. The three servers can be situated in the same availability zone, or across three availability zones to ensure the best availability. However, you can configure high availability with two availability zones.
Note:

Ensure that your kernel or Kubernetes node has the value of its inotify watches set high enough so that the Developer Portal can monitor and maintain the files for each Developer Portal site. If set too low, the Developer Portal containers might fail to start or go into a non-ready state when this limit is reached. If you have many Developer Portal sites, or if your sites contain a lot of content, for example, many custom modules and themes, then a larger number of inotify watches are required. You can start with a value of 65,000, but for large deployments, this value might need to go up as high as 1,000,000. The Developer Portal containers take inotify watches only when they need them. The full number is not reserved or held, so it is acceptable to set this value high.

Procedure

  1. The commands for installing the Portal subsystem are described in the following table. Sample code is also provided.
    Note:
    • Although the site-backup parameters listed in the following table are optional, it's highly recommended that you include them in your installation, so that remote server backups of the portal database are also taken. If you don't want to configure these parameters at installation, you can configure them later, see Backing up and restoring the Developer Portal in a Kubernetes environment.
    • Host names and DNS entries may not be changed on a cluster after the initial installation.
    • The backup secret is a Kubernetes secret that contains your username and password for your backup database (sftp/s3). Only password-based authentication is supported for sftp and s3, not authentication based on public certificates and private keys. Password-based authentication for s3 requires that you generate an access key and secret. For example:
    Command Values/Definition
    apicup init Initializes the apicup installation utility and creates the apiconnect-up.yml configuration file
    apicup subsys create ptl portal --k8s Describes a Portal subsystem in the Kubernetes cluster. The identifier ptl is the name that you have assigned to your Portal service. You can assign it any name, as long as the identifier consists of lower case alphanumeric characters or '-', with no spaces, starts with an alphabetic character, and ends with an alphanumeric character. The command portal indicates that you are creating a Portal subsystem.
    apicup subsys set ptl extra-values-file <path/file name> - Path to the extra values file. One extra values file is permitted. The extra values file requires a .yaml format. It contains the ingress annotations and other settings for the subsystem. For an example of an extra values file for each subsystem, see Creating an extra values file in a Kubernetes environment.
    apicup subsys set ptl portal-admin <padmin>.<hostname>.<domainname> - The management endpoint for the Portal. All endpoints must be resolvable by DNS. Domain names that are used for endpoints cannot contain the underscore "_" character. See Pre-installation requirements. Refer to the deployment overview diagram for information about endpoints and certificates: Deployment overview for endpoints and certificates.
    apicup subsys set ptl portal-www <portal>.<hostname>.<domain name> - The endpoint for the public portal websites. All endpoints must be resolvable by DNS. Domain names that are used for endpoints cannot contain the underscore "_" character. See Pre-installation requirements. Multiple portal-www endpoints may be configured, as described here: Defining multiple portal endpoints for a Kubernetes environment.
    apicup subsys set ptl namespace <namespaceName> - Defines the namespace where the Portal service resides; every subsystem can be in a separate namespace. Valid namespaces are configured in Kubernetes prior to starting the API Connect installation
    apicup subsys set ptl storage-class <storageClass> - Refers to a valid StorageClass object in your Kubernetes cluster that supports dynamic PersistentVolume provisioning. Static or manual PersistentVolume provisioning can be used, but it requires additional steps that are not covered in this documentation. Block storage is required. Select a block storage format of your choosing in order for API Connect components to be supported. GlusterFS is not recommended as a storage option due to severe performance degradation. For AWS, the gp2 and io1 types of Elastic Block Storage (EBS) are supported. Note that NFS is not supported.
    apicup subsys set ptl registry <registry-uri> - The location where you are running the image registry (for example, Artifactory)
    apicup subsys set ptl registry-secret <registrySecret> - Kubernetes secret with Docker credentials to authenticate with the image registry. The value for registry-secret must match the name of the secret created by using the kubectl create secret command. It contains the Docker credentials for accessing the registry.
    apicup subsys set ptl www-storage-size-gb The default is 5GB. The recommended minimum is 5GB. The actual value depends on your environment. Used to store the php, html, and media files that comprise each Portal web site. Increase this size by at least 1GB for every 20 small sites that you want to host. Note that a single site with a lot of media can take many GB. If there is less than 128MB free, then the Portal will refuse to create new sites.
    apicup subsys set ptl backup-storage-size-gb The default is 5GB. The recommended minimum is 5GB. The actual value depends on your environment. Stores 7 days worth of compressed backups of each Portal website. Increase this by at least 3GB for every 20 small sites that you want to host. Note that a single site with a lot of media can take many GB per backup.
    apicup subsys set ptl db-storage-size-gb The default is 12GB. The recommended minimum is 12GB. The actual value might be higher than this but will depend upon your environment. Used for the database files. Increase this by at least 5GB for every 20 small sites that you want to host. Larger sites require more storage. If there is less than 2GB free, then the Portal refuses to create new sites.
    Note: For example, a Portal with 5 sites should set this value to 40 GB, or more. Using the default values is not recommended.
    apicup subsys set ptl db-logs-storage-size-gb The default is 2GB, and this size should not be changed from 2 GB. Storage used for the database logs. Reducing this value could result in the volume filling up and the database hanging. Making it larger will have no effect on the number of logs kept.
    apicup subsys set ptl admin-storage-size-gb The default is 1GB, and this size should not be changed from 1GB. Used for the internal state of the admin container. Reducing this value could result in the admin container failing. Making it larger will have no effect
    apicup subsys set ptl mode Determines whether the installation is for development, testing, and demo purposes, or for production. If not explicitly set, the mode will default to dev (development and testing) for versions 2018.4.1.4 and later. For versions 2018.4.1.3 and earlier, the default for mode is standard.
    • dev - (Default) Use dev mode for development, testing, and demonstration purposes. It allows one instance of each subsystem to be created.
    • standard - Use standard mode for production environments. It allows multiple instances of each subsystem to be created.
    apicup subsys set ptl ingress-type Must be explicitly set to route for an OpenShift environment. For a standard K8s environment, ingress-type defaults to ingress and there is no need to explicitly enter this parameter.
    apicup subsys set ptl site-backup-host The fully qualified domain name of the backup server, in lowercase only. Ensure that the Kubernetes nodes can access this host. If using object storage, enter Endpoint/Region. (The / character between the endpoint and region is required for the object storage setting.)
    apicup subsys set ptl site-backup-port The port for the protocol to connect to the site-backup-host. Defaults to 22 if not explicitly set. The backup port is not required for object storage.
    apicup subsys set ptl site-backup-auth-user The user name for the server specified in site-backup-host. If using object storage, the user name is the S3 Secret Key ID.
    apicup subsys set ptl site-backup-auth-pass The password for the server specified in site-backup-host. If using object storage, the password is the S3 Secret Access Key parameter. The password is stored in Base64 encoded format, and must not be edited directly in the apiconnect-up.yml file.
    apicup subsys set ptl site-backup-path The full path to the directory where the backup files are stored. For object storage, the path can be set to the bucket value or the bucket/subfolder value.
    apicup subsys set ptl site-backup-protocol The protocol that is used to communicate with your remote backup endpoint. Specify one of the following values:
    • sftp - for secure file transfer protocol
    • objstore - for S3 compatible object storage
    The default protocol is sftp.
    Note: The public certificate on the S3 storage provider must be signed by a known certificate authority that is trusted by API Connect. Use of an untrusted authority can cause the following error during backup upload: x509: certificate signed by unknown authority.
    apicup subsys set ptl site-backup-schedule The schedule for how often automatic Portal backups are run. The format for the schedule is any valid cron string, as follows:
    * * * * *
- - - - -
| | | | |
| | | | +----- day of week (0 - 6) (Sunday=0)
| | | +------- month (1 - 12)
| | +--------- day of month (1 - 31)
| +----------- hour (0 - 23)
+------------- min (0 - 59)
    For example: 30 22 * * 1 performs backups at 10:30 pm on Mondays.

    The default backup schedule is 0 2 * * * (runs every day at 2 am). The timezone for backups is UTC.
    apicup certs set ptl CERT_NAME [CERT_FILE KEY_FILE CA_FILE] [flags] - Set the required certificates for the subsystem. Custom certificates might be set, otherwise, default certificates are automatically configured. For information on what certificates are available and how to set them see: Working with certificates.
    apicup subsys set ptl license-version <license_type> <license_type> - Specify the type of license, either Production or Nonproduction. If not specified, the default value is Nonproduction.

    Note that the license type does not impact which Portal image to install. The API Connect Kubernetes Pod annotations productID and productName reflect the selected license.
    apicup subsys install ptl Starts the installation of the Portal service. 
    apicup subsys create ptl portal --k8s
apicup subsys set ptl extra-values-file=<path/file name>
apicup subsys set ptl portal-admin=<padmin>.<hostname>.<domainname>
apicup subsys set ptl portal-www=<portal>.<hostname>.<domainname>
apicup subsys set ptl registry=<registry-uri>
apicup subsys set ptl namespace=<namespaceName>
apicup subsys set ptl registry-secret=<registrySecret> 
apicup subsys set ptl storage-class=<storageClass>
apicup subsys set ptl www-storage-size-gb=5
apicup subsys set ptl backup-storage-size-gb=5
apicup subsys set ptl db-storage-size-gb=12
apicup subsys set ptl db-logs-storage-size-gb=2
apicup subsys set ptl admin-storage-size-gb=1
apicup subsys set ptl mode=dev
apicup subsys set ptl ingress-type=route <for OpenShift environments only>

// OPTIONAL: Set the backup parameters
apicup subsys set ptl site-backup-host=<hostname>
apicup subsys set ptl site-backup-port=<22>
apicup subsys set ptl site-backup-auth-user=<username>
apicup subsys set ptl site-backup-auth-pass=<password>
apicup subsys set ptl site-backup-path=</site-backups>
apicup subsys set ptl site-backup-protocol=<sftp, objstore>
apicup subsys set ptl site-backup-schedule=<"0 0 * * *"> 

// OPTIONAL: Set the certificates 
apicup certs set ptl CERT_NAME=[CERT_FILE KEY_FILE CA_FILE] [flags]

// OPTIONAL: Write the plan to an output directory to inspect myProject/install-plan prior to installation
apicup subsys install ptl --out=ptl-install-plan
// Start the installation from the output directory. Enter the full path to the output directory.
apicup subsys install ptl --plan-dir=./myProject/ptl-install-plan

// If output file is not used, enter the following command to start the installation
apicup subsys install ptl
    The Portal endpoints correspond to the values entered when configuring a Portal service in the Cloud Manager. See Registering a Portal service.
    • apicup subsys set ptl portal-admin - This is the Management Endpoint that is defined in Cloud Manager, which is used for communicating with API Manager.
    • apicup subsys set ptl portal-www - This is the Portal Website URL defined in Cloud Manager. It determines the URL for the site that is created for each Catalog. It is used for public access to the Portal from a browser.
  2. After running the apicup subsys install command, run the apicup subsys get <portal_subsys_name> --validate command to validate the installation. You must correct any errors that are indicated by the --validate command before continuing. The following example output shows how an error in the installation is displayed: 
    Kubernetes settings
===================

Name                       Value
----                       -----
extra-values-file                                                             ✔
ingress-type               ingress                                            ✔
mode                       dev                                                ✔
namespace                  default                                            ✔
registry                   apic-dev-docker-local.artifactory.devops.com       ✔
registry-secret            apiconnect-image-pull-secret                       ✔
storage-class              -                                                  ✔


Subsystem settings
==================

Name                       Value
----                       -----
admin-storage-size-gb      2                                                  ✔
backup-storage-size-gb     5                                                  ✔
db-logs-storage-size-gb    2                                                  ✔
db-storage-size-gb         1                                                  ✘  db-storage-size-gb must be 12 or greater
site-backup-auth-pass      mypass                                             ✔
site-backup-auth-user      myuser                                             ✔
site-backup-host           1.2.3.4                                            ✔
site-backup-path           /home/fvtuser/site-backups                         ✔
site-backup-port           22                                                 ✔
site-backup-schedule       0 2 * * *                                          ✔
www-storage-size-gb        5                                                  ✔

Endpoints
=========

Name                       Value
----                       -----
portal-admin               api.portal.default.minikube                        ✔
portal-www                 portal.default.minikube                            ✔

What to do next

If you've not already done so, you can continue your API Connect installation by installing the other subsystems.