Custom Resources and Custom Resource Definitions

Information about the Custom Resources (CRs) that make up API Connect.

Custom Resources (CRs) are sets of Kubernetes resources (such as pods) that you can interact with using the kubectl command. An API Connect installation has a distinct CR for each API Connect subsystem: management, portal, gateway, and analytics.

Custom Resource Definitions (CRDs) are the Kubernetes resource that is used to define CRs. API Connect has a CRD for each subsystem:
  • ManagementCluster
  • PortalCluster
  • GatewayCluster
  • AnalyticsCluster
API Connect on Cloud Pak for Integration or on OpenShift with the top-level CR, has an extra CRD for the top-level CR:
  • APIConnectCluster
Each API Connect subsystem CR defines the system-level properties for its subsystem such as endpoints, secrets, backup settings, and storage allocations. The properties are defined in YAML format. The syntax to view the properties of an API Connect CR are:
kubectl -n <namespace> get <API Connect CRD name> <API Connect CR name> -o yaml
Example output:
apiVersion: management.apiconnect.ibm.com/v1beta1
kind: ManagementCluster
metadata:
  annotations:
    ...
  creationTimestamp: "2023-12-06T17:37:28Z"
    ...
  name: management
  namespace: apic
  ...
  uid: 9e67df02-d044-4a5b-8fb5-93391722ae97
spec:
  adminUser:
    secretName: management-admin-pass
  ...
  analytics:
    client: {}
    ingestion:
      secretName: management-a7s-ing-client
  apiManagerEndpoint:
    annotations:
      cert-manager.io/issuer: management-ingress-issuer
      haproxy.router.openshift.io/timeout: 240s
    hosts:
    - name: management-api-manager-apic.apps.ibm.com
      secretName: management-api-manager
    ...
  databaseBackup:
    ...
  databaseVolumeClaimTemplate:
    storageClassName: rook-ceph-block
    ...
  version: 10.0.x.y
  ...
status:
  conditions:
  - lastTransitionTime: "2023-12-06T17:47:47Z"
    message: All services ready
    reason: na
    status: "True"
    type: Ready
...
To refer to a specific property in the CR, dot notation is used, so the property:
metadata:
  annotations:
is referred to as metadata.annotations. In the example output shown previously, some properties of interest are highlighted in bold:
  • kind: ManagementCluster. The kind property refers to the CRD that defines the CR.
  • name: management. The name of the CR itself. When you want to run a kubectl operation on the CR, you specify the CR name in the command.
  • namespace: apic. The name of the namespace the CR exists in.
  • spec: The spec section contains the properties of your API Connect subsystem, such as URLs for the endpoints and scheduled database backup settings.
  • spec.apiManagerEndpoint.hosts.name is where you define the URL of the API Manager UI.
  • status: The status section shows information about the current state of the subsystem, including any errors or warnings.
You can have multiple portal, analytics, and gateway CRs in the same namespace, each registered with the management subsystem as separate services. You cannot have multiple management CRs in the same namespace. To list all the installed CRs for a portal, analytics, or gateway CRD, run:
kubectl get <CRD name>
where <CRD name> is PortalCluster, GatewayCluster, or AnalyticsCluster. Example output:
kubectl get PortalCluster

NAME        READY   STATUS    VERSION    RECONCILED VERSION   MESSAGE                                            AGE
ptl_1       3/3     Running   10.0.x.y   10.0.x.y-3968        Ready for API Cloud Manager service registration   6d22h
ptl_2       3/3     Running   10.0.x.y   10.0.x.y-3968        Ready for API Cloud Manager service registration   9d12h
The output shows two portal CRs. To get just information on one of the CRs, specify that CR name in the kubectl get command:
kubectl get PortalCluster ptl_2

NAME        READY   STATUS    VERSION    RECONCILED VERSION   MESSAGE                                            AGE
ptl_2       3/3     Running   10.0.x.y   10.0.x.y-3968        Ready for API Cloud Manager service registration   9d12h
Tip: Instead of typing the full CRD names ManagementCluster, PortalCluster, GatewayCluster, or AnalyticsCluster, you can use the following shorter alternatives:
  • mgmt for ManagementCluster
  • ptl for PortalCluster
  • gw for GatewayCluster
  • a7s for AnalyticsCluster
To see all the API Connect CRs in a namespace, use the kubectl get apic command:
kubectl get apic -n <namespace>
NAME      
                                               READY   STATUS    VERSION    RECONCILED VERSION   AGE
analyticscluster.analytics.apiconnect.ibm.com/test-a7s   n/n     Running   10.0.x.y   10.0.x.y-2248        5d

NAME                                                READY   STATUS    VERSION    RECONCILED VERSION   AGE
gatewaycluster.gateway.apiconnect.ibm.com/test-gw   n/n     Running   10.0.x.y   10.0.x.y-2248        5d

NAME                                                        READY   STATUS    VERSION    RECONCILED VERSION   AGE
managementcluster.management.apiconnect.ibm.com/test-mgmt   n/n   Running   10.0.x.y   10.0.x.y-2248        5d1h

NAME                                               READY   STATUS    VERSION    RECONCILED VERSION   MESSAGE                 AGE
portalcluster.portal.apiconnect.ibm.com/test-ptl   n/n     Running   10.0.x.y   10.0.x.y-2248        Ready to create sites   5d