Enabling the IBM App Connect Enterprise Agent in an App Connect Dashboard instance

You can enable the IBM® App Connect Enterprise Agent in an App Connect Dashboard instance by adding parameters to the Dashboard custom resource (CR) to configure the Agent.

To enable the Agent in a new or an existing Dashboard instance, complete the following steps:

1. Create a secret that stores your watsonx.ai credentials.

   In the YAML manifest that is provided for creating the secret, complete the fields as follows:

   • metadata.name: Either specify the default name of ace-agents-configuration for the secret, or specify a custom name of your choice for the secret.
   • metadata.namespace: Specify the namespace (or project) in which you want to create the secret. The new or existing Dashboard must also be deployed in this namespace.
   • stringData: Specify the watsonx.ai API key, host URL, and project ID in plain text. These values will be Base64 encoded in the secret that is created.

   Complete the relevant steps to create the secret in your operating system.

   • Linux® only:
     1. From the command line, log in to your cluster by using the oc login command or the relevant command for your Kubernetes environment.
     2. Run the following command to create the secret from the command line:
        

        cat <<EOF | oc apply -f -
        apiVersion: v1
        kind: Secret
        metadata:
          name: mySecret
          namespace: namespaceName
        type: Opaque
        stringData:
          WATSONX_API_KEY: watsonxAPIkey
          WATSONX_HOST_URL: watsonxHostURL
          WATSONX_PROJECT_ID: watsonxProjectID
        EOF

        

        cat <<EOF | kubectl apply -f -
        apiVersion: v1
        kind: Secret
        metadata:
          name: mySecret
          namespace: namespaceName
        type: Opaque
        stringData:
          WATSONX_API_KEY: watsonxAPIkey
          WATSONX_HOST_URL: watsonxHostURL
          WATSONX_PROJECT_ID: watsonxProjectID
        EOF

   • Linux or Windows:
     1. From the command line, log in to your cluster by using the oc login command or the relevant command for your Kubernetes environment.
     2. From your local computer, create and then save a YAML file (for example, watsonxcreds_cr.yaml) with the following content.

        apiVersion: v1
        kind: Secret
        metadata:
          name: mySecret
          namespace: namespaceName
        stringData:
          WATSONX_API_KEY: watsonxAPIkey
          WATSONX_HOST_URL: watsonxHostURL
          WATSONX_PROJECT_ID: watsonxProjectID
        type: Opaque

        Example:

        apiVersion: v1
        kind: Secret
        metadata:
          name: ace-agents-configuration
          namespace: ace-fiona
        stringData:
          WATSONX_API_KEY: 01Abcde1234abc5-678d-9012-efgh-3i45678j905d
          WATSONX_HOST_URL: https://us-south.ml.cloud.ibm.com
          WATSONX_PROJECT_ID: a123bc4d-ef56-78g9-0h12-ij345667k8l2
        type: Opaque

     3. Run the following command to create the secret. (Use the name of the .yaml file that you created.)
        

        oc apply -f watsonxcreds_cr.yaml

        

        kubectl apply -f watsonxcreds_cr.yaml

   Either complete step 2 to enable the Agent in a Dashboard instance that you are creating, or complete step 3 to enable the Agent in an existing Dashboard instance.

2. To enable the Agent when you create a Dashboard instance, complete the following steps:
   1. If necessary, review the following information in the App Connect Dashboard reference: prerequisites, Red Hat OpenShift SecurityContextConstraints requirements, resources required, storage, and data encryption.
   2. Create a Dashboard instance as documented in App Connect Dashboard reference: Creating an instance, and then wait for the Dashboard instance to get to a Ready state.
      Notable Dashboard CR settings for enabling the Agent:

      • Ensure that the specified license matches a Dashboard version that supports the Agent:
        • Use spec.license.license to specify the license identifier for a 13.0.7.0-r1 or later version of the Dashboard.
        • Use spec.version to set the version of the Dashboard instance to a value that resolves to 13.0.7.0-r1 or later.
      • Set spec.agents.enabled to true to enable the IBM App Connect Enterprise Agent.
      • Set spec.agents.customSecretName to the name of the secret that you created in step 1 to store the credentials for your IBM watsonx.ai Runtime service.
        • If you set the name of the secret to the default value of ace-agents-configuration, leave spec.agents.customSecretName unspecified to automatically use ace-agents-configuration as the secret.
        • If you set the name of the secret to a custom name of your choice, set spec.agents.customSecretName to this value.
      • Set spec.api.enabled to true (the default) to enable the API for IBM App Connect in containers for use with the Dashboard. To run natural language queries (which involve GET operations) against the managed resources in your Dashboard and the deployment environment, this API must be enabled for the Dashboard instance.
      • If using IBM Cloud Kubernetes Service in a Kubernetes environment, set spec.ingress.enabled to true to enable automatic creation of ingress resources for the Dashboard UI and the API. The Dashboard instance will manage the lifecycle of both of these ingress resources.

        In all other Kubernetes environments, you will need to manually create ingress resources for the Dashboard UI and the API after the Dashboard is created.

      • If you want to be able to view audit event details for the Agent, ensure that spec.logFormat is set to json. (Audit logging is automatically enabled for an Agent in a Dashboard instance and cannot be disabled.) The JSON setting is needed to format the logs with a predefined list of fields, which record audit event details for user interactions in the Agent chat window. For more information, see Viewing audit information for the App Connect Dashboard.

      The following example shows a partially completed Dashboard CR with notable settings for creating a Dashboard instance with the Agent enabled on Red Hat OpenShift.

      Example 1

      apiVersion: appconnect.ibm.com/v1beta1
      kind: Dashboard
      ...
      spec:
        license:
          accept: true
          license: L-CGSU-AUCFFB
          use: AppConnectEnterpriseProduction
        agents:
          enabled: true
          customSecretName: secretName
        api:
          enabled: true
        version: '13.0'
        logFormat: json
      ...

      The following example shows a partially completed Dashboard CR with notable settings for creating a Dashboard instance with the Agent enabled on IBM Cloud Kubernetes Service. In this Kubernetes environment, ingress is enabled, which automatically creates ingress resources for the Dashboard UI and for the API.

      Example 2

      apiVersion: appconnect.ibm.com/v1beta1
      kind: Dashboard
      ...
      spec:
        license:
          accept: true
          license: L-CGSU-AUCFFB
          use: AppConnectEnterpriseProduction
        agents:
          enabled: true
          customSecretName: secretName
        ingress:
          enabled: true
        api:
          enabled: true
        version: '13.0'
        logFormat: json
      ...

3. To enable the Agent in an existing Dashboard instance, edit the Dashboard CR to specify the relevant settings. If the UI of the Dashboard instance is currently open in a browser tab, you can leave the Dashboard UI open.
   1. Open the CR in YAML view. For more information, see App Connect Dashboard reference: Updating the custom resource settings for an instance.
   2. Set spec.agents.enabled to true, ensure that spec.agents.customSecretName correctly identifies the name of the secret that stores your watsonx.ai credentials, and ensure that the remaining requisite settings are completed. For information about all of the notable Dashboard CR settings for enabling the Agent, see step 2.
   3. Save the YAML definition to apply your changes and then wait for the Dashboard instance to get to a Ready state.
4. If Keycloak is enabled to authenticate users and authorize access to the Dashboard instance, ensure that you are assigned the dashboard-admin role that is defined for the Dashboard instance in the Keycloak Admin Console. This role grants full user access with administrative privileges to the Dashboard instance and is needed to interact with the Agent.

   For more information, see Implementing identity and access management for App Connect Designer and App Connect Dashboard instances.