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.
- 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. - 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>
- OpenShift:
- Add your IBM entitlement key to the
introspection.yaml
manifest file.- 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
. Theintrospection.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 associatedNodePort
. - 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.
- In the extracted CASE bundle, locate the file called
- 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 linesname: driver-storage emptyDir: {}
with
name: driver-storage persistentVolumeClaim: claimName: introspection-drivers
- Apply the updated manifest file to your cluster.
- Apply the
introspection.yaml
manifest file with the following command (for OpenShift, replacekubectl
withoc
):kubectl apply -f introspection.yaml
- Verify that the introspection service is running with the following command (for OpenShift,
replace
kubectl
withoc
):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
- Apply the
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.
- Create a file named
introspection-route.yaml
with the following contents (replacemy-rosa-cluster.abcd.p1
with your actual cluster domain, and replacecert-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
- Run the following command to apply the file, which installs the new route into the cluster:
oc apply -f introspection-route.yaml
- Create a file named
- Set up an ingress in Kubernetes
- To set up a route, the Introspection Service must be running.
- 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 calledintrospection-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
- Run the following command to apply the file, which installs the new ingress into the
cluster:
kubectl apply -f introspection-ingress.yaml
- Create a file named
Using the Introspection Service
For information on logging in to the Introspection Service, see Setting up your environment