Installing an on-premises Introspection Service

Install an on-premises Introspection Service on the Red Hat OpenShift Container Platform or native Kubernetes cluster where API Connect for GraphQL is deployed.

The Introspection Service is a development feature that allows a GraphQL schema to be automatically extracted from a REST/GraphQL endpoint or SQL database.

By default, API Connect for GraphQL uses a public introspection service, hosted by IBM. If you want to use introspection with private services such as those on intranets and cluster-only networks, you can deploy the API Connect Essentials GraphQL Introspection service on-premises.

Complete the procedures in the following sections to install the introspection service:

Prerequisites

You must install API Connect for GraphQL before attempting to install the Introspection Service.

You will install the Introspection Service on the same cluster (and in the same namespace) as API Connect for GraphQL, so you should have already downloaded the CASE bundle to the cluster, and set up access to IBM Container Software Library with an image pull secret (see the API Connect Essentials installation prerequisites).

Install the Introspection Service

Complete the following steps to install the Introspection Service.

  1. Log in to the cluster as an administrator.

    Ensure that you are authenticated to your cluster and can run oc/kubectl commands with admin privileges.

  2. Set the context to the namespace where API Connect for GraphQL is installed:
    • OpenShift:
      oc project <my-namespace>
    • Kubernetes:
      kubectl config set-context --current --namespace=<my-namespace>
  3. Add your IBM entitlement key to the introspection.yaml manifest file.
    1. In the extracted CASE bundle, locate the file called introspection.yaml.

      When you installed API Connect Essentials, you extracted the CASE bundle and it created a directory called ibm-stepzen-case. The introspection.yaml file is located in the following subdirectory:

      ibm-stepzen-case/inventory/stepzenGraphOperator/files/deploy

      This file is a Kubernetes manifest defining the introspection service and the associated NodePort.

    2. Edit the file and replace the value in the spec.template.spec.imagePullSecrets.name field with the name of your image pull secret, which you created when you installed API Connect Essentials.
  4. If you are installing Db2 or Oracle, you need to provide the JDBC drivers. Store these drivers in a Persistent Volume (PV) that can be accessed using Persistent Volume Claim (PVC). To create PVC, refer to the provided sample. Update the introspection.yaml with your PVC. Replace the lines
    name: driver-storage   
    emptyDir: {} 

    with

    name: driver-storage
    persistentVolumeClaim:
       claimName: introspection-drivers

  5. Apply the updated manifest file to your cluster.
    1. Apply the introspection.yaml manifest file with the following command (for OpenShift, replace kubectl with oc):
      kubectl apply -f introspection.yaml
    2. Verify that the introspection service is running with the following command (for OpenShift, replace kubectl with oc):
      kubectl get service introspection 

      When the installation completes successfully, you see a message similar to the following example:

      NAME            TYPE       CLUSTER-IP    EXTERNAL-IP   PORT(S)        AGE
      introspection   NodePort   172.30.40.4   <none>        80:30048/TCP   2m17s

Set up a route or ingress

To expose the Introspection Service to the internet, you must create a route (OpenShift) or an ingress (Kubernetes).

Set up a route in OpenShift Container Platform
To set up a route, the Introspection Service must be running.
  1. Create a file named introspection-route.yaml with the following contents (replace my-rosa-cluster.abcd.p1 with your actual cluster domain, and replace cert-manager.io/issuer-name if you intend to use different cluster issuer):
    apiVersion: route.openshift.io/v1
    kind: Route
    metadata:
      annotations:
        cert-manager.io/issuer-kind: ClusterIssuer
        cert-manager.io/issuer-name: letsencrypt
        haproxy.router.openshift.io/balance: random
        haproxy.router.openshift.io/disable_cookies: "true"
        haproxy.router.openshift.io/hsts_header: max-age=31536000;includeSubDomains;preload
        haproxy.router.openshift.io/timeout: 30s
        haproxy.router.openshift.io/timeout-tunnel: 5d
      name: introspection-route
    spec:
      host: stepzen-introspection.apps.my-rosa-cluster.abcd.p1.openshiftapps.com
      port:
        targetPort: introspection-port
      tls:
        insecureEdgeTerminationPolicy: None
        termination: edge
      to:
        kind: Service
        name: stepzen-introspection
        weight: 150
      wildcardPolicy: None
  2. Run the following command to apply the file, which installs the new route into the cluster:
oc apply -f introspection-route.yaml
Set up an ingress in Kubernetes
To set up a route, the Introspection Service must be running.
  1. Create a file named introspection-ingress.yaml with the following contents:

    This example assumes you have obtained an SSL certificate for the domain stepzen-introspection.my-domain.io (or alternatively, a wildcard certificate for *.my-domain.io) and stored it in the secret called introspection-cert.

        apiVersion: networking.k8s.io/v1
        kind: Ingress
        metadata:
          name: introspection-ingress
          annotations:
            nginx.ingress.kubernetes.io/rewrite-target: /
        spec:
          defaultBackend:
            service:
              name: introspection
              port:
                number: 80
          tls:
          - hosts: ['stepzen-introspection.my-domain.io']
            secretName: introspection-cert
          rules:
          - host: stepzen.test-zen.io
            http:
              paths:
              - path: /stepzen-subscriptions/
                pathType: Prefix
                backend:
                  service:
                    name: stepzen-graph-server-subscription
                    port:
                      number: 80
  2. Run the following command to apply the file, which installs the new ingress into the cluster:
    kubectl apply -f introspection-ingress.yaml

Using the Introspection Service

For information on logging in to the Introspection Service, see Setting up your environment