Installing the analytics subsystem

Install the analytics subsystem by creating and applying the ingress-ca, common-issuer, and analytics_cr yaml files.

Before you begin

Important: When you install the analytics subsystem, you must configure the analytics subsystem so that communication from the management subsystem is secured with either mTLS or JWT. For more information on inter-subsystem communication, see Network requirements for inter-subsystem communication.

When installing subsystems in different namespaces you must first create the cert-manager issuers and certificates required by that subsystem in the same namespace.

  1. Using the file obtained from Extracting the management ingress-ca certificates, run: oc apply -f ingress-ca.yaml -n <analytics namespace>
  2. Create a file called common-issuer.yaml and paste in these contents:
    Note: If you have just done Installing the portal subsystem then you will already have this file.
    #
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
# 
#     http://www.apache.org/licenses/LICENSE-2.0
# 
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#

---

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: selfsigning-issuer
  labels:
    app.kubernetes.io/instance: management
    app.kubernetes.io/managed-by: ibm-apiconnect
    app.kubernetes.io/name: selfsigning-issuer
spec:
  selfSigned: {}
---
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: ingress-issuer
  labels:
    app.kubernetes.io/instance: management
    app.kubernetes.io/managed-by: ibm-apiconnect
    app.kubernetes.io/name: ingress-issuer
spec:
  ca:
    secretName: ingress-ca
  3. Apply the above yaml file with: oc apply -f common-issuer.yaml -n <analytics namespace>
  4. Confirm that the issuers were created and are in ready state: oc get issuers -n <analytics namespace>
    
oc get issuers -n <analytics namespace>
NAME                 READY
ingress-issuer       True
selfsigning-issuer   True

About this task

Use the OpenShift CLI to edit the custom resource template for the analytics subsystem, apply the resource, verify that the pods are up and running.

Procedure

  1. Create a file that is called analytics_cr.yaml and paste in these contents: 
    #
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
# 
#     http://www.apache.org/licenses/LICENSE-2.0
# 
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#

apiVersion: analytics.apiconnect.ibm.com/v1beta1
kind: AnalyticsCluster
metadata:
  name: analytics
  labels:
    app.kubernetes.io/instance: analytics
    app.kubernetes.io/managed-by: ibm-apiconnect
    app.kubernetes.io/name: analytics
annotations:
    apiconnect-operator/cp4i: "false"
spec:
  version: $APP_PRODUCT_VERSION
  license:
    accept: $LICENSE_ACCEPTANCE
    use: $LICENSE_USE
    license: '$LICENSE_ID'
  profile: $PROFILE
  microServiceSecurity: certManager
  certManagerIssuer:
    name: selfsigning-issuer
    kind: Issuer
  ingestion:
    endpoint:
      annotations:
        cert-manager.io/issuer: ingress-issuer
      hosts: 
      - name: ai.$STACK_HOST
        secretName: analytics-ai-endpoint
    clientSubjectDN: CN=analytics-ingestion-client,O=cert-manager
  storage:
    type: $STORAGE_TYPE
    shared:
      volumeClaimTemplate:
        storageClassName: $STORAGE_CLASS
        volumeSize: $DATA_VOLUME_SIZE 
   #master: # uncomment this section if you set storage.type = dedicated.
   #  volumeClaimTemplate:
   #    storageClassName: $STORAGE_CLASS
  2. Edit the YAML file and set the variables:
    $APP_PRODUCT_VERSION
    API Connect application version for the subsystems. 
    version: <version_number>

    Example version number: 10.0.8.1

    $PROFILE
    Specify your analytics subsystem profile, 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 Deployment and component profiles.
    Note: The profile that you select influences your storage type options. If you select an n1 profile then you must select the shared storage type. For more information about storage types, see storage types.
    $STACK_HOST
    The desired ingress subdomain for the API Connect stack. Used when specifying endpoints. Domain names that are used for endpoints cannot contain the underscore "_" character. You can customize the subdomain or the complete hostname:
    • Subdomain customization only

      Accept the prefixes predefined for the ingress hostnames to use and replace all instances of $STACK_HOST with the desired ingress subdomain for the API Connect stack. For example, if your host is myhost.subnet.example.com:

      
  ingestion:
    endpoint:
       < ... >
      hosts: 
      - name: ai.myhost.subnet.example.com
        secret: analytics-ai-endpoint
       < .... >
    • Complete hostname customization

      Change both the predefined prefixes and the $STACK_HOST subdomain to match your desired hostnames.

      For example, you can replace $STACK_HOST with my.analytics.ingestion.myhost.subnet.example.com, where my.analytics.ingestion replaces ai, and myhost.subnet.example.com replaces STACK_HOST. 

      ingestion:
    endpoint: 
      < ... >
      hosts:
      - name: my.analytics.ingestion.myhost.subnet.example.com
        secret: analytics-ai-endpoint 
       < ... >
    $STORAGE_TYPE
    If you set $PROFILE to an n1 (one replica) profile, then set this to shared. If you set $PROFILE to an n3 (three replica) profile then set this to dedicated and uncomment the storage.master section, for example:
      storage:
    type: dedicated
    shared:
      volumeClaimTemplate:
        storageClassName: $STORAGE_CLASS
        volumeSize: $DATA_VOLUME_SIZE
    master:
      volumeClaimTemplate:
        storageClassName: $STORAGE_CLASS

    For more information about storage types, see dedicated or shared storage.

    $STORAGE_CLASS
    The Kubernetes storage class to be used for persistent volume claims. For more information, see Analytics preinstallation planning. Find the available storage classes in the target cluster by running the following command: oc get sc. Example:
    storage:
    type: shared
    shared:
      volumeClaimTemplate:
        storageClassName: ceph-block
    $DATA_VOLUME_SIZE

    Size of storage allocated for data. To estimate the storage space you require, see Estimating storage requirements. If you are unable to estimate your storage requirement then set it to 500Gi.

    storage:
    type: shared
    shared:
      volumeClaimTemplate:
        storageClassName: ceph-block
        volumeSize: 500Gi
    $LICENSE_ACCEPTANCE
    Set accept to true. You must accept the license to successfully deploy API Connect.
    $LICENSE_USE
    Set use to either production or nonproduction to match the license that you purchased.
    $LICENSE_ID
    Set license: to the license ID for the version of API Connect that you purchased. See API Connect licenses.
  3. Optional: If Cloud Pak for Integration is installed, and you want your API Connect installation to be integrated with it, then set metadata.annotations.apiconnect-operator/cp4i to true.

    This annotation enables integration with Cloud Pak for Integration.

  4. Optional: If you want to disable mTLS for communications between the management and analytics subsystem, and between the gateway and analytics subsystem, and enable JWT instead, then add and set the properties mtlsValidateClient and jwksUrl. 
    spec:
  ...
  mtlsValidateClient: false
  jwksUrl: <JWKS URL>
    where <JWKS URL> is the URL of the JWKS endpoint that is hosted on the management subsystems. To find out the jwksUrl, describe the management CR and check the status: section:
    kubectl describe mgmt -n <namespace>
...
status:
  - name: jwksUrl
    secretName: api-endpoint
    type: API
    uri: https://api.apic.acme.com/api/cloud/oauth2/certs
    For more information about JWT security, see Enable JWT security instead of mTLS.
    Note: It is not possible to use JWT on the V5 compatible gateway to analytics message flow.
  5. Optional: If you plan to configure analytics database backups, then define the storage that is required for backups:
    Define your backup PVC by adding the backup.volumeClaimTemplate property in spec.storage. For example:
    spec:
  storage:
    backup:
      volumeClaimTemplate:
        storageClassName: <storage class>
        volumeSize: <size>

    If you are not sure of the volume size that you need, then you can configure the backup.volumeClaimTemplate after installation.

  6. Install the analytics subsystem by applying the modified CR with the following command: 
    oc apply -f analytics_cr.yaml -n <namespace>
  7. Verify that the analytics subsystem is fully installed: 
    oc get AnalyticsCluster -n <namespace>

    The installation is complete when READY shows all pods running (n/n), and the STATUS reports Running. Example:

    NAME        READY   STATUS    VERSION          RECONCILED VERSION   AGE
analytics   n/n     Running   10.0.8.0   10.0.8.0-1281    86m

    It is not necessary to wait for analytics installation to complete before you move on to the next subsystem installation.

  8. Backup your analytics subsystem and configure scheduled analytics database backups: Backing up and restoring the analytics subsystem.

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.