App Connect Dashboard reference

Supported storage types

The following storage types can be used to allocate storage for the content server:

Persistent storage

With this storage type, any BAR files that you upload to the App Connect Dashboard (while creating an integration server) or that you import (by using the "BAR files" page in the Dashboard) are stored in a persistent volume in the container’s file system. The persistent volume can be dynamically provisioned through a storage class that is available on the cluster, or can be requested through a claim name. Persistent storage is recommended for extra resilience because the BAR files are retained in the content-server when pods restart and are deleted only when you delete the Dashboard.

The App Connect Dashboard requires a file-based storage class with ReadWriteMany (RWX) capability. If using IBM Cloud, use the ibmc-file-gold-gid storage class.

The file system must not be root-owned and must allow read/write access for the user that the Dashboard runs as. This user is a random unique identifier (UID) that is chosen by the Red Hat OpenShift cluster for all restricted pods in a given namespace.

If using Azure File storage, the owner user identifier (UID) of the Azure File mounted directory is different from the process UID of the container. From the Dashboard's pod YAML resource, get the uid value from the runAsUser field. For more information, see Considerations when using Azure File.

If you choose persistent storage, you will need to specify a storage class or the name of an existing claim, the storage size, and optionally, a label selector.

Ephemeral storage

With this storage type, an ephemeral volume is created when a Dashboard pod is started, and uploaded or imported BAR files are stored in this volume in the container’s file system. The ephemeral (emptyDir) volume exists only for the lifetime of the pod, so the BAR files will be lost when the pod restarts. You might typically choose this storage type if creating an environment for demonstration or testing.

If you choose ephemeral storage, you can specify a storage size limit for the volume.

Simple Storage Service (S3) storage

S3 storage offers an alternative option to persistent storage, and enables the content server to support the use of an object storage service for BAR file storage by using the S3 REST API.

Note: S3 storage is applicable only if the spec.version value in the App Connect Dashboard custom resource resolves to 12.0.1.0-r1 or later.

Restriction:

• S3 storage is not supported when the IBM App Connect Operator is installed in a restricted network because a cluster requires internet access to read and write BAR files from or to an S3 object store.
• Only Amazon S3 and IBM Cloud Object Storage S3 are supported as S3 providers.

Any BAR files that you upload or import to the Dashboard will be stored with read/write access in a specified bucket in your S3 instance. These BAR files will all be visible on the "BAR files" page (which presents a view of the content server) and can also be viewed in the S3 bucket. An uploaded or imported BAR file is stored with a generated static token, which is hidden in the Dashboard UI, but visible as an object within the S3 bucket.

BAR files and associated tokens that are stored as objects in a bucket follow a naming convention, as shown in the following example for a BAR file named CustomerDatabaseV1.bar:

/mnt/data/content/CustomerDatabaseV1/bars/CustomerDatabaseV1.bar

/mnt/data/content/CustomerDatabaseV1/.token

If you choose S3 storage, you will need to specify the following storage settings for your provisioned S3 instance:

• The name of an existing bucket for storing uploaded or imported BAR files

  Although you are not restricted from using an S3 bucket that already contains other objects, a dedicated bucket for BAR file storage is recommended. If you decide to use a bucket that contains other objects, the App Connect Dashboard will ignore those objects because they have no association with the content server.

  Note: If different instances of the App Connect Dashboard are configured to use the same S3 bucket with the same credentials and endpoint, BAR files that are uploaded or imported to the content server from either Dashboard will be visible on the "BAR files" page in both Dashboards and can be deployed from these Dashboards.
• An S3 endpoint to which the S3 REST API sends requests for reading and writing objects

  You should be able to locate the available endpoints from your S3 instance. For example, on IBM Cloud Object Storage S3, you can locate the endpoints from the Endpoints page.

  To minimize latency, it is recommended that you use an S3 bucket that is in the same geographic area as your App Connect Dashboard instance. Also use an endpoint with a location or region that is similar to where the Dashboard is deployed. For more information, see Endpoints and storage locations in the IBM Cloud Object Storage S3 documentation and Amazon Simple Storage Service endpoints and quotas in the Amazon Web Services documentation.

• S3 credentials for connecting to the bucket

  You will need to supply these credentials by creating a configuration of type S3Credentials. For more information, see Creating a configuration of type S3Credentials for use with the App Connect Dashboard.

To define the storage type when creating an App Connect Dashboard instance, you must specify your preferred type in the custom resource settings by setting the spec.storage.type parameter and then complete the other spec.storage.* parameters as appropriate for the selected storage type. If you want to create an S3-compatible Dashboard, your must first create a configuration object of type S3Credentials to store the credentials for accessing the bucket.

Creating an instance from the IBM Cloud Pak Platform UI

To create an App Connect Dashboard instance from the IBM Cloud Pak Platform UI, complete the following steps:

1. From a browser window, log in to the IBM Cloud Pak Platform UI.
   Tip: You can use the generated URL for a deployed IBM Cloud Pak for Integration Platform UI instance to access the IBM Cloud Pak Platform UI.

   The Platform UI home page opens with cards and navigation menu options that provide access to the instances and other resources that you are authorized to create, manage, or use. For information about completing administration tasks (such as user management or platform customization) from this page, see Platform UI in the IBM Cloud Pak foundational services documentation.

2. From the navigation menu , expand Administration and click Integration instances.
3. From the "Integration instances" page, click Create an instance.
4. To create an App Connect Dashboard instance from the Create an instance page, click the Integration dashboard tile and click Next.
5. From the "Create an integration dashboard" page, click a tile to select which type of instance you want to create:
   • Quick start: Deploy a development dashboard with one replica pod.
   • Production: Deploy a production dashboard with multiple replica pods for resilience and high availability.
6. Click Next. A UI form view opens with the minimum configuration required to create the instance.
7. Complete either of the following steps:
   • To quickly get going, complete the standard set of configuration fields. You can display advanced settings in the UI form view by setting Advanced settings to On. Note that some fields might not be represented in the form.
     • Name: Enter a short distinctive name that uniquely identifies this Dashboard.
     • Namespace: Enter the name of the namespace (project) where you want to create the Dashboard instance.
     • Channel or version: Select an App Connect product (fix pack) version that the Dashboard is based on. You can select a channel that will resolve to the latest fully qualified version on that channel, or select a specific fully qualified version. If you are using IBM App Connect Operator 5.0.4 or later, the supported channels or versions will depend on the Red Hat OpenShift version that is installed in your cluster. For more information about these values, see spec.version values.
     • Accept: Review the license in the supplied link and then click this check box to accept the terms and conditions.
     • License LI: Select a license identifier that aligns with the channel or the fully qualified version that you selected. For more information, see Licensing reference for IBM App Connect Operator.
     • License use: Select an appropriate CloudPakForIntegration or AppConnectEnterprise license type that you are entitled to use.
     • Replicas: Specify the number of replica pods to run for this deployment.
     • Storage type: Select the type of storage to use for storing BAR files that are uploaded or imported to the Dashboard.
       • persistent-claim: Choose this option for storage in a persistent volume in the container’s file system.
       • ephemeral: Choose this option for storage in an ephemeral volume that exists only for the lifetime of the pod.
       • s3: Choose this option for storage in a bucket in a Simple Storage Service (S3) instance.

       For more information, see Supported storage types.

     • Storage class: If preferred for a persistent volume, select a supported storage class for your cluster, which should be used to dynamically provision a persistent volume that belongs to that class.

       When Storage type is set to persistent-claim, either Storage class or Claim Name is required.

     • Claim Name: If preferred for a persistent volume, specify the name of an existing claim that should be used to request a persistent volume for BAR file storage. This claim must exist in the same namespace as the Dashboard.

       When Storage type is set to persistent-claim, either Storage class or Claim Name is required.

     • Size: Specify the maximum amount of storage required for a persistent volume in decimal or binary format; that is, Gi or G. This value is required if Storage type is set to persistent-claim.
     • s3 bucket: Specify the name of an existing bucket that is used for object storage in a Simple Storage Service (S3) instance. You must have read/write access to this bucket, which will be used to store BAR files that are uploaded or imported to the Dashboard. This value is required if Storage type is set to s3.

       For a list of supported S3 providers and considerations for choosing a bucket, see Supported storage types.

     • s3 host: Specify an endpoint that is associated with your Simple Storage Service (S3) system, to which the S3 REST API sends requests for reading and writing objects to the bucket specified in s3 bucket. This value is required if Storage type is set to s3.
     • s3 configuration: Specify the name of an existing configuration object of type S3Credentials, which stores credentials for accessing the bucket specified in s3 bucket. Set this parameter to the Name (or metadata.name) value that was specified while creating the configuration. This value is required if Storage type is set to s3.
   • For a more advanced configuration, click YAML to switch to the YAML view and then update the editor with your required parameters.
     • For information about the available parameters and their values, see Custom resource values.
     • For information about the supported storage types for storing BAR files that are uploaded to the App Connect Dashboard, see Storage. You can use the spec.storage.* parameters to allocate this storage. Note that you will not be able to change the storage type of your App Connect Dashboard instance after it's created.
     • For licensing information, see Licensing reference for IBM App Connect Operator.
8. Click Create. You are redirected to the Integration instances page. An entry for the instance is shown in the table with an initial status of Pending, which you can click to check the progress of the deployment. When the deployment completes, the status changes to Ready.
   

Users with the required permission can access this Dashboard (Integration dashboard) instance by clicking the name, and then use the instance to deploy Designer and Toolkit integrations to integration servers.

Creating an instance from the Red Hat OpenShift web console

To create an App Connect Dashboard instance by using the Red Hat OpenShift web console, complete the following steps:

1. Applicable to IBM Cloud Pak for Integration only:
   1. If not already logged in, log in to the IBM Cloud Pak Platform UI for your cluster.
   2. From the Platform UI home page, click Install operators or OpenShift Container Platform, and log in if prompted.
2. Applicable to an independent deployment of IBM App Connect Operator only: From a browser window, log in to the Red Hat OpenShift Container Platform web console. Ensure that you are in the Administrator perspective .
3. From the navigation, click Operators > Installed Operators.
4. If required, select the namespace (project) in which you installed the IBM App Connect Operator.
5. From the Installed Operators page, click IBM App Connect.
6. From the Operator details page for the App Connect Operator, click the Dashboard tab.
7. Click Create Dashboard.

   From the Details tab on the Operator details page, you can also locate the Dashboard tile and click Create instance to specify installation settings for the instance.

8. To use the Form view, ensure that Form view is selected and then complete the fields. Note that some fields might not be represented in the form. For information about completing the standard set of configuration fields, refer to the field descriptions in Creating an instance from the IBM Cloud Pak Platform UI. (In the web console, the namespace or project is not included in the form and should already be selected from an earlier step.)
9. Optional: For a finer level of control over your installation settings, click YAML view to switch to the YAML view. Update the content of the YAML editor with the parameters and values that you require for this Dashboard instance.
   • To view the full set of parameters and values available, see Custom resource values.
   • For information about the supported storage types for storing BAR files that are uploaded to the App Connect Dashboard, see Storage. You can use the spec.storage.* parameters to allocate this storage. Note that you will not be able to change the storage type of your App Connect Dashboard instance after it's created.
   • For licensing information, see Licensing reference for IBM App Connect Operator.
10. Click Create to start the deployment. An entry for the Dashboard instance is shown in the Dashboards table, initially with a Pending status.
11. Click the Dashboard name to view information about its definition and current status.

    On the Details tab of the page, the Conditions section reveals the progress of the deployment.

    Note: The Admin UI field provides the URL for accessing the Dashboard instance. You can also locate this URL under Networking > Routes in the console navigation.

    

    Share this URL with users who have access to this namespace, and who will need to use the Dashboard instance to deploy integration servers.

    You can use the breadcrumb trail to return to the (previous) Operator details page for the App Connect Operator. When the deployment is complete, the status is shown as Ready in the Dashboards table.

Creating an instance from the Red Hat OpenShift CLI

To create an App Connect Dashboard instance from the Red Hat OpenShift CLI, complete the following steps.

1. From your local computer, create a YAML file that contains the configuration for the App Connect Dashboard instance that you want to create. Include the metadata.namespace parameter to identify the namespace in which you want to create the instance; this should be the same namespace where the other App Connect instances or resources are created.
   • To view the full set of parameters and values that you can specify, see Custom resource values.
   • For information about the supported storage types for storing BAR files that are uploaded to the App Connect Dashboard, see Storage. You can use the spec.storage.* parameters to allocate this storage. Note that you will not be able to change the storage type of your App Connect Dashboard instance after it's created.
   • For licensing information, see Licensing reference for IBM App Connect Operator.

   The following examples (Example 1 and Example 2) show a Dashboard CR with settings for a persistent-claim storage type:

   Example 1:

   apiVersion: appconnect.ibm.com/v1beta1
   kind: Dashboard
   metadata:
     name: db-prod
     namespace: mynamespace
   spec:
     license:
       accept: true
       license: L-QECF-MBXVLU
       use: CloudPakForIntegrationNonProduction
     pod:
       containers:
         content-server:
           resources:
             limits:
               cpu: 250m
               memory: 512Mi
             requests:
               cpu: 50m
               memory: 50Mi
         control-ui:
           resources:
             limits:
               cpu: 500m
               memory: 512Mi
             requests:
               cpu: 50m
               memory: 125Mi
     replicas: 3
     storage:
       size: 5Gi
       type: persistent-claim
       class: ibmc-file-gold-gid
     useCommonServices: true
     version: 12.0-lts

   Example 2:

   apiVersion: appconnect.ibm.com/v1beta1
   kind: Dashboard
   metadata:
     name: db-prod
     namespace: mynamespace
   spec:
     license:
       accept: true
       license: L-QECF-MBXVLU
       use: AppConnectEnterpriseProduction
     pod:
       containers:
         content-server:
           resources:
             limits:
               cpu: 250m
               memory: 512Mi
             requests:
               cpu: 50m
               memory: 50Mi
         control-ui:
           resources:
             limits:
               cpu: 500m
               memory: 512Mi
             requests:
               cpu: 50m
               memory: 125Mi
     replicas: 3
     storage:
       size: 5Gi
       type: persistent-claim
       class: valid-storage-class
     useCommonServices: false
     version: 12.0-lts

   The following examples (Example 3 and Example 4) show a Dashboard CR with settings for an s3 storage type:

   Example 3:

   apiVersion: appconnect.ibm.com/v1beta1
   kind: Dashboard
   metadata:
     name: db-prod
     namespace: mynamespace
   spec:
     license:
       accept: true
       license: L-QECF-MBXVLU
       use: CloudPakForIntegrationNonProduction
     pod:
       containers:
         content-server:
           resources:
             limits:
               cpu: 250m
               memory: 512Mi
             requests:
               cpu: 50m
               memory: 50Mi
         control-ui:
           resources:
             limits:
               cpu: 500m
               memory: 512Mi
             requests:
               cpu: 50m
               memory: 125Mi
     replicas: 3
     storage:
       size: 5Gi
       type: s3
       bucket: appc-operator-e2e
       host: s3.eu-gb.cloud-object-storage.appdomain.cloud
       s3Configuration: s3credentials-ibmcosiam
     useCommonServices: true
     version: 12.0-lts

   Example 4:

   apiVersion: appconnect.ibm.com/v1beta1
   kind: Dashboard
   metadata:
     name: db-prod
     namespace: mynamespace
   spec:
     license:
       accept: true
       license: L-QECF-MBXVLU
       use: AppConnectEnterpriseProduction
     pod:
       containers:
         content-server:
           resources:
             limits:
               cpu: 250m
               memory: 512Mi
             requests:
               cpu: 50m
               memory: 50Mi
         control-ui:
           resources:
             limits:
               cpu: 500m
               memory: 512Mi
             requests:
               cpu: 50m
               memory: 125Mi
     replicas: 3
     storage:
       size: 5Gi
       type: s3
       bucket: appc-operator-e2e
       host: s3.eu-gb.cloud-object-storage.appdomain.cloud
       s3Configuration: s3credentials-ibmcosiam
     useCommonServices: false
     version: 12.0-lts

2. Save this file with a .yaml extension; for example, dashboard_cr.yaml.
3. From the command line, log in to your Red Hat OpenShift cluster by using the oc login command.
4. Run the following command to create the App Connect Dashboard instance. (Use the name of the .yaml file that you created.)

   oc apply -f dashboard_cr.yaml

5. Run the following command to check the status of the App Connect Dashboard instance and verify that it is ready:

   oc get dashboards -n namespace

   The output will also provide the URL of the Dashboard instance; for example:

   NAME       RESOLVEDVERSION   REPLICAS   CUSTOMIMAGES   STATUS    URL                                                          AGE
   db-prod    12.0.12.2-r1-lts  3          false          Ready     https://db-prod-ui-mynamespace.apps.acecc-abcde.icp4i.com    9m12s

   
   Share the URL value in the output with users who have access to this namespace, and who will need to use the Dashboard instance to deploy integration servers.

Updating an instance from the IBM Cloud Pak Platform UI

To update an App Connect Dashboard instance from the IBM Cloud Pak Platform UI, complete the following steps:

1. From a browser window, log in to the IBM Cloud Pak Platform UI.
   Tip: You can use the generated URL for a deployed IBM Cloud Pak for Integration Platform UI instance to access the IBM Cloud Pak Platform UI.

   The Platform UI home page opens with cards and navigation menu options that provide access to the instances and other resources that you are authorized to create, manage, or use. For information about completing administration tasks (such as user management or platform customization) from this page, see Platform UI in the IBM Cloud Pak foundational services documentation.

2. From the navigation menu , expand Administration and click Integration instances.
3. From the "Integration instances" page, locate the App Connect Dashboard (Integration dashboard) instance that you want to update.
4. Click the options icon to open the options menu, and then click Edit. The "Edit" page opens for that instance.
5. Either use the fields in the "UI form" view or switch to the YAML view to update the required settings. You can update existing values, add new entries, or delete entries. For information about the available parameters and their values, see Custom resource values.
6. Click Update to save your changes.

Updating an instance from the Red Hat OpenShift web console

To update an App Connect Dashboard instance by using the Red Hat OpenShift web console, complete the following steps:

1. Applicable to IBM Cloud Pak for Integration only:
   1. If not already logged in, log in to the IBM Cloud Pak Platform UI for your cluster.
   2. From the Platform UI home page, click Install operators or OpenShift Container Platform, and log in if prompted.
2. Applicable to an independent deployment of IBM App Connect Operator only: From a browser window, log in to the Red Hat OpenShift Container Platform web console. Ensure that you are in the Administrator perspective .
3. From the navigation, click Operators > Installed Operators.
4. If required, select the namespace (project) in which you installed the IBM App Connect Operator.
5. From the Installed Operators page, click IBM App Connect.
6. From the Operator details page for the App Connect Operator, click the Dashboard tab.
7. Locate and click the name of the instance that you want to update.
8. Click the YAML tab.
9. Update the content of the YAML editor as required. You can update existing values, add new entries, or delete entries. For information about the available parameters and their values, see Custom resource values.
10. Click Save to save your changes.

Updating an instance from the Red Hat OpenShift CLI

To update an App Connect Dashboard instance from the Red Hat OpenShift CLI, complete the following steps.

1. From the command line, log in to your Red Hat OpenShift cluster by using the oc login command.
2. From the namespace where the Dashboard instance is deployed, run the oc edit command to partially update the instance, where instanceName is the name (metadata.name value) of the instance.

   oc edit dashboard instanceName

   The Dashboard CR automatically opens in the default text editor for your operating system.

3. Update the contents of the file as required. You can update existing values, add new entries, or delete entries. For information about the available parameters and their values, see Custom resource values.
4. Save the YAML definition and close the text editor to apply the changes.

oc patch dashboard instanceName --type='merge' --patch "$(cat updatesettings.yaml)"

Deleting an instance from the IBM Cloud Pak Platform UI

To delete an App Connect Dashboard instance from the IBM Cloud Pak Platform UI, complete the following steps:

1. From a browser window, log in to the IBM Cloud Pak Platform UI.
   Tip: You can use the generated URL for a deployed IBM Cloud Pak for Integration Platform UI instance to access the IBM Cloud Pak Platform UI.

   The Platform UI home page opens with cards and navigation menu options that provide access to the instances and other resources that you are authorized to create, manage, or use. For information about completing administration tasks (such as user management or platform customization) from this page, see Platform UI in the IBM Cloud Pak foundational services documentation.

2. From the navigation menu , expand Administration and click Integration instances.
3. From the "Integration instances" page, locate the App Connect Dashboard (Integration dashboard) instance that you want to delete.
4. Click the options icon () to open the options menu, and then click Delete.
5. Confirm the deletion.

Deleting an instance from the Red Hat OpenShift web console

To delete an App Connect Dashboard instance by using the Red Hat OpenShift web console, complete the following steps:

1. Applicable to IBM Cloud Pak for Integration only:
   1. If not already logged in, log in to the IBM Cloud Pak Platform UI for your cluster.
   2. From the Platform UI home page, click Install operators or OpenShift Container Platform, and log in if prompted.
2. Applicable to an independent deployment of IBM App Connect Operator only: From a browser window, log in to the Red Hat OpenShift Container Platform web console. Ensure that you are in the Administrator perspective .
3. From the navigation, click Operators > Installed Operators.
4. If required, select the namespace (project) in which you installed the IBM App Connect Operator.
5. From the Installed Operators page, click IBM App Connect.
6. From the Operator details page for the App Connect Operator, click the Dashboard tab.
7. Locate the instance that you want to delete.
8. Click the options icon () to open the options menu, and then click the Delete option.
9. Confirm the deletion.

Deleting an instance from the Red Hat OpenShift CLI

To delete an App Connect Dashboard instance from the Red Hat OpenShift CLI, complete the following steps.

1. From the command line, log in to your Red Hat OpenShift cluster by using the oc login command.
2. From the namespace where the Dashboard instance is deployed, run the following command to delete the instance, where instanceName is the value of the metadata.name parameter.

   oc delete dashboard instanceName