Installing the Developer Portal subsystem

Install the Developer Portal subsystem

Before you begin

Before you start this task, you should have already:

Reviewed the Kubernetes requirements in Pre-installation requirements
Completed Deploying operators and cert-manager
If installing as part of a Top-Level CR deployment, complete Configure the top-level APIConnectCluster for v12 subsystem support
Deployed the analytics subsystem. For more information. see Deploying analytics subsystem.

Important: Only one Developer Portal instance can reference an Analytics cluster. If you create a second Developer Portal instance that references the same Analytics cluster, a webhook error occurs. The error message similar to the following example is displayed:

The DevPortalCluster "devportal2" is invalid: spec.analyticsRef: Invalid value: {"name":"analytics","namespace":"apic"}: Cannot set DevPortal analyticsRef to the same value as set by datapower-nano-system/devportal

Before you install the Developer Portal subsystem, deploy the Analytics subsystem. Include devPortalMode: true in the Analytics Container Registry (CR) specification. For example,


apiVersion: analytics.apiconnect.ibm.com/v1beta1
kind: AnalyticsCluster
metadata:
  name: analytics
  namespace: apic
spec:
  devPortalMode: true
  version: 12.1.1.0
  license:
    accept: true
    use: production
    license: L-PXLC-N7T9RW
  profile: n1xc2.m16
  imagePullSecrets:
    - apic-registry-secret
  imageRegistry: my.docker.registry.domain.example.com
  microServiceSecurity: certManager
  certManagerIssuer:
    name: selfsigning-issuer
    kind: Issuer
  storage:
    type: shared
    shared:
      volumeClaimTemplate:
        storageClassName: REPLACE_STORAGE_CLASS_NAME
        volumeSize: 50Gi

Important:

Verify that all required secrets and certificates are available and correctly referenced in both CRs.
Use consistent image registry and operator versions across clusters in a multi-cluster environment.

Wait for readiness:


kubectl wait --for=condition=ready analyticsclusters.analytics.apiconnect.ibm.com --all -n <namespace> --timeout=1000s

About this task

To install the Developer Portal subsystem, define the Developer Portal Custom Resource (CR) in a YAML file. The YAML file contains all of your configuration settings for the Developer Portal deployment. Use the file to install, upgrade, and update the configuration of your Developer Portal subsystem.

Note: The template Custom Resource for Top-Level CR deployments differs from the standard template, and the endpoint structure varies for each subsystem. The TopLevel CR templates are stored in the helper_files/tlcr/folder. The devportal_cr.yaml template file is stored in the directory where you extracted helper_files.zip.

Procedure

Create encryption secret.
This secret stores the encryption key used by the Developer Portal subsystem for securing sensitive configuration values. The devportal_cr.yaml CR references this secret, so the encryption secret must exist before you apply the CR.
Note: If you do not specify an encryption secret, the system generates a random key. This key must be included in disaster recovery (DR), backup, and restore procedures. For customers migrating from version 11.1, the default key is yap-portal$.
To ensure consistency and simplify recovery, create the encryption secret before you create the Developer Portal (CR). For example,
```
kubectl create secret generic mydevportal-enc-key \
  --from-literal=PORTAL_SERVER_CONFIG_ENCRYPTION_KEY=yap-portAl$
```

Reference the secret in the Developer Portal CR:


spec:
  encryptionSecret:
    secretName: mydevportal-enc-key

Create Developer Portal admin secret that stores the credentials required for the Developer Portal subsystem administrator.
```
kubectl create secret generic devportal-admin-secret -n <namespace> 
   --from-literal=password=password-value
```
Important: The Developer Portal CR and the Developer Portal admin secret must be in same namespace.
Reference the secret in the Developer Portal CR:
```
spec:
  adminUser:
    secretName: devportal-admin-secret
                    
```
Note: If you do not create the admin secret and create its reference in the Developer Portal CR, then the system creates a random secret with a password value. During the start up of the subsystem, the system reads the secret and sets it as admin password. If you delete the Developer Portal CR, the admin secret is also deleted and the initial admin password is lost. However, the password is not removed from the database. In such case, if you reinstall the Developer Portal subsystem and if you create the admin secret, then the password will not be created from the latest admin secret as the old password is still persistent in the database. Hence, you must first create the admin secret to configure a password of your choice before you apply the Developer Portal CR.

Important: The initial UI password is configured through the Kubernetes secret during deployment. After deployment, updates to this secret do not affect the password. To change the password, you must update it directly in the Developer Portal UI.

Create or copy the devportal_cr.yaml file from the helper_files.zip.

Update the cert-manager.io/issuer annotation under devportalAdminEndpoint and devportalUIEndpoint.
```
annotations: 
    cert-manager.io/issuer: your-issuer-name
```

Update the certManagerIssuer section to reference the correct issuer name and kind.


certManagerIssuer:  
      name: your-issuer-name  
      kind: Issuer

For example,

apiVersion: devportal.apiconnect.ibm.com/v1beta1
kind: DevPortalCluster
metadata:
  name: devportal
#  annotations:
#    apiconnect-operator/wmapigateway-client-secret: devportal-wmapigateway-client
spec:
  version: $APP_PRODUCT_VERSION
  profile: $PROFILE
  devportalAdminEndpoint:
    #ingressClassName: $INGRESS_CLASS
    annotations:
      cert-manager.io/issuer: ingress-issuer
    hosts:
    - name: api.devportal.$STACK_HOST
      secretName: devportal-admin
  devportalUIEndpoint:
    #ingressClassName: $INGRESS_CLASS
    annotations:
      cert-manager.io/issuer: ingress-issuer
    hosts:
    - name: devportal.$STACK_HOST
      secretName: devportal-web
  adminClientSubjectDN: |
    CN=devportal-admin-client,O=cert-manager
    CN=wmapigateway-devportal-client,O=cert-manager
  microServiceSecurity: certManager
  certManagerIssuer:
    name: selfsigning-issuer
    kind: Issuer
  license:
    accept: false
    use: production
    license: ''
# encryptionSecret:
#   secretName: devportal-enc-key
  analyticsRef:
    name: $ANALYTICS_REF_NAME
    namespace: $ANALYTICS_REF_NAMESPACE
  isStandalone: false

You can uncomment the following encryptionSecretRef field from the devportal_cr.yaml, enable it, or keep it in the CR as per your requirement:


# encryptionSecret:
#  secretName: devportal-enc-key

Edit the CR file and update the following settings:
$APP_PRODUCT_VERSION
API Connect application version for the subsystems.
```
version: <version_number>
```
Example version number: 12.1.1.0
$PROFILE

Specify your Developer Portal subsystem profile.

The profile format is nXcYmZ, where n indicates number of replicas, c number of cores, and m is the minimum memory allocation in GB. For more information on profiles, see Developer Portal component deployment profile limits.

$ANALYTICS_REF_NAME, and $ANALYTICS_REF_NAMESPACE
Enter the name and namespace of the deployed Analytics CR.
For example:
```
Spec:
analyticsRef: 
    name: analytics
    namespace: apic
```
Important: The Developer Portal cluster can be installed in a different namespace from the analytics cluster. In such cases, the analyticsRef.namespace field is used to locate the analytics cluster across namespaces. For more information, see Installing the analytics subsystem in a shared namespace.
devportal.$STACK_HOST
Enter domain name that corresponds to the desired subdomain for accessing the API Connect user interface.
For example:
```
name: devportal.cp.apps.example.com
secretName: devportal-web
```
api.devportal.$STACK_HOST
Enter domain name that corresponds to the subdomain through which the admin interface of API Connect will be accessed.
For example:
```
name: devportal.cp.apps.example.com
secretName: devportal-web
```
Edit the license setting.
1. Set accept: to true to accept the license. The default value is false. If you do not accept the license, the Operator does not install the subsystem.
2. Set metric: to track your product usage. Enter the unit of measure that is used for your program license:
  - PROCESSOR_VALUE_UNIT - Default value. If you leave the field blank, this value is used.
  - MONTHLY_API_CALL - Applies only to the IBM API Connect Hybrid Entitlement program.
  For information on tracking monthly call volume, see Counting total API calls.
3. Set use: to either production or nonproduction to match the license you purchased.
4. Set license: to the license ID for the version of API Connect that you purchased. See API Connect licenses.
Example entry to accept the license for a production system:
```
  license:
    accept: true
    metric: PROCESSOR_VALUE_UNIT 
    use: production
    license: L-PXLC-N7T9RW
```
Configure isStandalone.
Set isStandalone to True to register Developer Portal with multiple API Connect instances. It does not inherit the Federated API Management settings from any instance. You must manually configure the Federated API Management settings in the Developer Portal user interface.
Set isStandalone to False to register Developer Portal with only one API Connect instance. It automatically inherits the Federated API Management settings from that instance. By default, isStandalone is set to false.
```
isStandalone: false
```
Save the file.
Run the following command to apply the devportal_cr.yaml:
```
kubectl apply -f path/to/devportal_cr.yaml -n <namespace>
```
where:
- path/to/devportal_cr.yaml is the path to your saved devportal_cr.yaml file.
- namespace is the name of your namespace.
Verify that the Developer Portal subsystem is fully installed by running the following command:
```
kubectl get devportalcluster -n <namespace>
```
where

namespace

The name of your namespace.

Wait for the Developer Portal cluster to be ready.


kubectl wait --for=condition=ready devportalclusters.devportal.apiconnect.ibm.com --all -n <namespace> --timeout=1000s

The installation is complete when the READY status is True and the SUMMARY reports that all services are online. Example:


  NAME        READY      STATUS          VERSION                    RECONCILED VERSION                 MESSAGE         AGE
devportal      5/5       Running         12.1.0.0                   12.1.0.0-0           Dev Portal is ready        4d10h

The READY total count is based on your configured topology. Both numbers are equal when the installation is complete.

To access the Developer Portal user interface, open a browser and go to https://devportal.$STACK_HOST.
Log in with the default credentials:
```
username: administrator
password: manage
```

What to do next

If you are creating a new deployment of API Connect, install other subsystems as needed.

When you have completed the installation of all required API Connect subsystems, you can proceed to defining your API Connect configuration by using the API Connect Cloud Manager; refer to the Cloud Manager configuration checklist.