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
-
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.
-
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
- Edit the
license:
setting:
- 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.
- 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.
- Set
use:
to either production
or
nonproduction
, to match the license you purchased.
- 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
- 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.
-
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