Creating the analytics CR

Create the installation CR for IBM® API Connect analytics so that you can deploy the analytics subsystem.

About this task

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.
To install the analytics subsystem, create a Custom Resource (CR) in a .yaml file. The file contains all of your configuration settings for the analytics deployment. Use the file to install, upgrade, and update the configuration of your analytics subsystem.
Note: The analytics_cr.yaml and analytics_dedicated_cr.yaml template files are stored in the directory where you extracted helper_files.zip.

Procedure

  1. Create or copy the appropriate analytics CR file from the helper_files, depending on which deployment storage type you want, see: Planning the analytics profile, storage class, and storage type.
    • If you want to use shared storage, use analytics_cr.yaml.
    • If you want to use dedicated storage use analytics_dedicated_cr.yaml. Dedicated storage is only supported on three replica deployments.
  2. Edit the CR file and update the following settings:

    You cannot install the analytics subsystem until the placeholders are replaced with real values for your environment.

    $APP_PRODUCT_VERSION
    API Connect application version for the subsystems.
    version: <version_number>

    Example version number: 10.0.5.8

    $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 Planning your deployment topology.

    $SECRET_NAME
    The name of the secret used to pull images from the Docker registry.
    imagePullSecrets:
      - apic-registry-secret
    $DOCKER_REGISTRY
    The host name of the Docker Registry to which you uploaded the installation images. For example:
    my.docker.registry.domain.example.com.
    $INGRESS_CLASS
    The ingress class that you want the endpoint to use. This is an optional property and if not specified, the ingress class with annotation ingressclass.kubernetes.io/is-default-class: true is used. If such an ingress class does not exist in the Kubernetes environment, then nginx is used. If you do set this value, it must refer to a valid ingress class configured in your Kubernetes system.
    Note: This property is commented out in the template CR file. If you set this value, make sure to also uncomment it.
    $STACK_HOST
    The desired ingress subdomain for the API Connect stack. Used when specifying the ingestion endpoint. Domain names that are used for endpoints cannot contain the underscore "_" character. You can customize the subdomain or the complete host name:
    • Subdomain customization only

      Accept the prefixes predefined for the ingress host names 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
              secretName: analytics-ai-endpoint
             < .... >
    $STORAGE_CLASS
    The Kubernetes storage class to be used for persistent volume claims (for more information, see Planning the analytics profile, storage class, and storage type). Find the available storage classes in the target cluster by running the following command: kubectl get sc.
    • For shared storage deployments:
        storage:
          type: shared
          shared:
            volumeClaimTemplate:
              storageClassName: local_storage
    • For dedicated storage deployments, set $STORAGE_CLASS in two places:
        storage:
          type: dedicated
          shared:
            volumeClaimTemplate:
              storageClassName: local_storage
              ...
          master:
            volumeClaimTemplate:
              storageClassName: local_storage
              ...
    $DATA_VOLUME_SIZE

    Replace $DATA_VOLUME_SIZE with the value that you calculated in Data storage: calculate how much data you want to store. If not specified it defaults to 50Gi

      storage:
        ...
        shared:
          volumeClaimTemplate:
            ...
            volumeSize: 50Gi
  3. Edit the license: setting:
    1. Set accept: to true to accept the license. Note that the default value is false. If you do not accept the license, the Operator will 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 Tracking API volume for auditing and compliance.

    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-RJON-CEBL97
  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 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 on 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. Save the file.

Results

You now have an analytics CR that is configured with the default analytics topology described in Planning your topology.

What to do next

If you do not want to add any more configuration options, skip to the topic Installing analytics.
Important: All additional analytics configuration options can be added, changed, or removed after installation except for disablement or enablement of internal storage. If you want to disable internal storage you must configure this in the analytics CR before installation: Disabling internal storage

Otherwise, add configuration options to the CR as explained in Topology settings and additional analytics features