Creating an integration server to run your BAR file resources

To create an integration server, complete the following steps:

1. Access your App Connect Dashboard instance in either of the following ways:
   • Applicable to Cloud Pak for Integration only: From your cluster, log in to the IBM Cloud Pak Platform UI and open the App Connect Dashboard.
   • Applicable to App Connect Enterprise certified container only: To access your App Connect Dashboard instance, open a browser window and enter the URL that your administrator provided for the App Connect Dashboard instance. Enter your login credentials.

   The Welcome page for the App Connect Dashboard is displayed. If shown, you can click the Servers tile to view any deployed integration servers, or click the Integrations tile to view the underlying integrations. You can also create an integration server from the Deploy integrations tile (or the Create a server tile if using an older Dashboard instance), and you can view the documentation from the Learn more tile.

   
2. Complete either of the following steps depending on your location:
   • From the Welcome page, click the Deploy integrations tile (or click Create a server if using an older Dashboard instance).
   • From the navigation pane, click the Dashboard icon to open the Servers page. Any existing integration servers in the namespace are displayed as tiles on this page.

     
     Click Deploy integrations (or Create server if using an older Dashboard instance).

     
3. From the Size view on the Deploy integrations page, click the appropriate integration tile to deploy an integration that you obtained from any of these environments: (If using an older Dashboard instance, click the appropriate integration tile from the Type view on the Create an Integration Server page.)
   • One or more BAR files that you exported from an App Connect Designer instance in your cluster or from an App Connect on IBM Cloud service instance
   • One or more BAR files that you developed as a hybrid by using both App Connect Designer (or App Connect on IBM Cloud) and IBM App Connect Enterprise Toolkit

   Click a tile that corresponds to the size of the integration to be deployed. (Review the VPC, CPU, Memory, and Storage sizings on the tiles for guidance.)

   • Quick start integration
   • Small integration
   • Medium integration
   • Large integration

   Tip: A virtual processor core (VPC) is a unit of measurement that is used to determine the licensing cost of IBM products. It is based on the number of virtual cores (vCPUs) that are available to the product. The CPU values on the tiles are measured in cores.
   
4. Click Next to proceed to the next stage.
5. From the Integrations view, complete either of these steps to provide one or more BAR files that you want to deploy. You can choose to deploy a single BAR file that is stored in the Dashboard's content server, or you can deploy one or more BAR files that are stored in an external repository.
   • To deploy a BAR file from the content server, use one of the following methods to add the required file to the content server or to choose a BAR file that is already stored in the content server. (This example uses a BAR file that was exported for an API flow.)
     • Drag and drop the required file from its location in an open file browser into the boxed area.
     • Click within the boxed area to open a file browser and locate the BAR file.
     • From the drop-down list, select an existing BAR file that was previously uploaded to the content server. (This option is useful if you want to create more than one integration server from the same BAR file to manage your workloads.)
     
   • To deploy one or more BAR files that are stored in an external repository, no selections are required at this stage. As the instructions indicate, you can specify the BAR files later when you get to the (final) Properties view (or the Server view if using an older Dashboard instance).
     
6. Click Next.
7. From the Configuration view, select or create one or more configurations that you want to apply to the integration server.
   • If these configurations have previously been created, select the required entries in the configurations table by clicking the check boxes.
   • If you need to create configurations, click Create configuration to open the Create configuration panel, select the configuration type, and then complete the details. When you click Create, the configuration is added to the table, and is selected by default.
   Note:

   • For a Designer integration (BAR file) that you exported from an App Connect Designer or App Connect on IBM Cloud instance, only the following configuration types are relevant.
     • Accounts: If you want to use local connectors to run one or more operations in the integration server, you'll require the account details for these connectors. Only one configuration of type Accounts can be selected for the integration server, but this configuration can contain account details for multiple connectors. You can configure account details by clicking Create configuration, selecting Accounts from the Type field, and then completing the details. For more information, see Accounts type.

       If the BAR file was exported for an event-driven flow, you must create a local account for the application that is used to trigger the flow because only local accounts are supported for events.

     • Agentx: If your App Connect Dashboard instance is configured to use a switch server for callable flow capability, and a Callable flow node was configured in the exported flow, you need an Agentx file that enables connections to the switch server. A preconfigured default-agentx entry is available in the configurations table by default, and is automatically selected for use with the integration server. This entry represents the configuration for a locally deployed switch server. Clear this check box only if you would prefer to use an external switch server. Only one configuration of type Agentx can be selected for the integration server. For information about creating a configuration for an external switch server, see Agentx type. You must select this new configuration entry for the integration server before you create the server.

       An AgentA configuration object is also created by default for the switch server, and is presented as a default-agenta entry is in the configurations table.

       Note that only one agent configuration is permitted per integration server. If you select both default-agentx and default-agenta, an error message is generated when you try to create the server.

     • Private Network Agent: If the deployed integration needs to interact with an application in a private network, you need to provide secure connectivity details to establish a connection. These details enable port forwarding from a local listening port that is opened for the deployed integration to the remote port and host of the application in the private network. Only one configuration of type Private Network Agent can be selected for the integration server. For a Designer integration, you can select the check box for a generated configuration of type Private Network Agent, which is available in the configurations table and which automatically enables port forwarding. Choose the specific configuration that is associated with the private network connection that you configured for your Designer flow from the Private network connections page in your App Connect Designer instance. For more information, see Connecting to a private network from App Connect Designer and Connecting your integration to applications in the private network.
     • setdbparms.txt: If you are deploying an integration server at version 12.0.3.0-r1 or earlier, and you want to use cloud-managed (App Connect on IBM Cloud) connectors to run one or more operations in the integration server, you'll need to specify an IBM Cloud API key. Your deployed integration can use this API key to authenticate to your App Connect on IBM Cloud instance, in order to connect to the connectors and accounts that were referenced in the exported flow. You can specify this key by clicking Create configuration, selecting setdbparms.txt from the Type field, and then completing the details. For more information, see setdbparms.txt type.
   • For a Designer integration (BAR file) that you developed as a hybrid, you can select or create multiple valid configurations that apply for your BAR file definition. For more information, see Configuration types for integration servers and integration runtimes.
     
   • If you would like to deploy one or more BAR files that are stored in an external repository, select or create a configuration object of type BarAuth, which specifies the credentials for connecting to this repository, as described in BarAuth type.

   

   Note: If an App Connect Designer instance is created in the same namespace as your App Connect Dashboard instance, the configurations table includes configurations that were automatically created when the Designer instance was created. These configurations are prefixed with the name of the Designer instance. For example, if the Designer instance is named des-01-quickstart-ma, you'll see configurations of various types that are named in the format des-01-quickstart-ma-designer-xxx, where xxx represents an abbreviation of the configuration type. You cannot delete these configurations.
8. Click Next.
9. From the Properties view (or Server view if using an older Dashboard instance), define details about the integration server and install the BAR file resources:
   1. Complete the default fields:
      • Name: Enter a short distinctive name that uniquely identifies this integration server.
      • Channel or version: Select an App Connect product (fix pack) version that the integration server 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 7.1.0 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.
        Note: If you select a fully qualified version of 11.0.0.10-r2 or earlier, or select a channel that resolves to 11.0.0.10-r2 or earlier, you must ensure that the Designer flows type field is clear because it is not supported for these versions.
      • License LI: Select a license identifier that aligns with the channel or a 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.
      • Designer flows mode: Specify what type of connectors you want to use:
        • all: Select this option to use any combination of cloud-managed or local connectors.
          Note: The all value is available only if the Channel or version value (that is, spec.version) resolves to 12.0.3.0-r1 or earlier, and it is deprecated in those versions.

          This option extends the functionality of each pod by deploying sidecar containers, which are needed to run flows that are authored in App Connect Designer, and to run local connectors. (You’ll need to have configuration objects of type setdbparms.txt and Accounts, which contain an IBM Cloud API key and local account credentials.)

          If you select this option, a local connector is used if a successful connection can be established with the supplied credentials. If the connection fails or if local credentials were not supplied, the cloud-managed connector is used. The operation fails if the connection to the cloud-managed connector also fails.

        • local: Select this option to use local connectors only. This option extends the functionality of each pod by deploying sidecar containers, which are needed to run flows that are authored in App Connect Designer, and to run local connectors. (You’ll need to have a configuration object of type Accounts that contains local account credentials.)

          If you select this option, a local connector is used if a successful connection can be established with the supplied credentials. Otherwise, the operation fails.

      • Designer flows type: Specify what type of flows are supported:
        • api-flows: Select this option to enable support for API flows only.
        • event-driven-or-api-flows: Select this option to enable support for both event-driven and API flows. You must select this option if your exported BAR file contains an event-driven flow, but it can also be used if deploying an API flow. Note that the resource requirements are higher for this option.
        Note: The Designer flows type field is not supported for version 11.0.0.10-r2 or earlier, so if you select a value for Designer flows type, you must ensure that a supported value is selected in the Channel or version field. If required, you can clear the Designer flows type field by clicking the x next to the selected value.
      • Force Flow HTTPS: Set this switch to on to force all HTTP Input nodes and SOAP Input nodes in all deployed flows (including their usage for inbound connections to applications, REST APIs, and integration services) in the integration server to use Transport Layer Security (TLS).

        When Force Flow HTTPS is set to on, you must also ensure that https is selected as the protocol in the The type of transport used by the integration endpoint field.

        Note: The Force Flow HTTPS switch is not supported for version 12.0.1.0-r3 or earlier, so if set to on, you must ensure that a supported value is selected in the Channel or version field.
      • Force Flow HTTPS Secret Reference: Specify the name of a secret that stores a user-supplied public certificate/private key pair to use for enforcing TLS. (You can use tools such as keytool or OpenSSL to generate the certificate and key if required, but do not need to apply password protection.) This field is displayed only when Force Flow HTTPS is set to on.

        A secret is required if Force Flow HTTPS is set to on. You must create the secret in the namespace where the integration server will be deployed, and can do so from the Red Hat OpenShift web console, or from the Red Hat OpenShift or Kubernetes CLI. Use your preferred method to create the secret. For example, you can use the following Secret (YAML) resource to create the secret from the web console (by using the Import YAML icon ) or from the CLI (by running oc apply -f resourceFile.yaml):

        apiVersion: v1
        kind: Secret
        metadata:
          name: secretName
          namespace: namespaceName
        data:
          tls.crt: "base64Encoded_crt_publicCertificate"
          tls.key: "base64Encoded_key_privateKey"
        type: kubernetes.io/tls

        Or you can create the secret by running the following command:

        oc create secret tls secretName --key filename.key --cert filename.crt

        Note:

        When you create the integration server, the IBM App Connect Operator checks for the certificate and key in the secret and adds them to a generated keystore that is protected with a password. The endpoint of the deployed integration is then secured with this certificate and key. If the secret can't be found in the namespace, the integration server will fail after 10 minutes.

        If you need to update the certificate and key that are stored in the secret, you can edit the Secret resource to update the tls.crt and tls.key values. When you save, the keystore is regenerated and used by the integration server without the need for a restart.

      • The type of transport used by the integration endpoint: Select a transport protocol that defines whether the endpoint of the deployed integration is secured.
        • http: Choose this option if you are not using HTTPS-based REST API flows in the integration. When set to http, the endpoint is configured as http and is not secured. The http option uses port 7800 by default.
        • https: Choose this option to indicate that you are using HTTPS-based REST API flows (with TLS configured). To use this option, you must have configured all HTTP Input nodes and SOAP Input nodes in all flows in the integration to use TLS either by setting the Force Flow HTTPS switch to on, or by using mechanisms such as the server.conf.yaml file while developing the flows in IBM App Connect Enterprise. When set to https (with the prerequisite TLS configuration), the endpoint for the deployed integration is configured as secured with the https protocol. The https option uses port 7843 by default.

        If using a Kubernetes environment, this setting is ignored. Instead, the protocol that is defined in the ingress definition for this integration server, which you will need to create later, will be used. For more information, see Creating ingress definitions for external access to your IBM App Connect instances.)

      • Enable Operations Dashboard tracing: Set this switch to on to enable transaction tracing, which will push trace data to the IBM Cloud Pak for Integration Operations Dashboard to aid with problem investigation and troubleshooting. An Operations Dashboard (Integration tracing) instance must be available to process the required registration approval for tracing.
        Note: The Enable Operations Dashboard tracing switch is available only if the Channel or version value (that is, spec.version) resolves to 12.0.8.0-r1 or earlier, and it is deprecated in those versions. Support for the Operations Dashboard is also available only in IBM Cloud Pak for Integration 2022.4.1 or earlier, and it is deprecated in those versions.
      • Operations Dashboard namespace: Specify the namespace where the Operations Dashboard (Integration tracing) was deployed.
        Note: The Operations Dashboard namespace field is available only if the Channel or version value (that is, spec.version) resolves to 12.0.8.0-r1 or earlier. The field is deprecated in those versions and is displayed only when Enable Operations Dashboard tracing is set to on.

      
   2. Display advanced settings by switching Advanced settings to on, and then populate any of the additional fields that are displayed.
      • Advanced: Bar URL: If you did not provide a BAR file for deployment earlier (from the Integrations view) because you would like to deploy one or more co-related BAR files that are stored in an external repository, specify a comma-separated list of these BAR files from the external HTTP or HTTPS endpoint. Specify the URL to each file including the file name; for example:

        https://artifactory.com/myrepo/getHostnameAPI.bar,https://artifactory.com/myrepo/CustomerDatabaseV1.bar

        Tip: If you are using GitHub as an external repository, you must specify the raw URL. Sample formats are as follows:
        https://raw.github.ibm.com/somedir/main/bars/getHostAPI.bar
https://github.com/johndoe/somedir/raw/main/getHostAPI.bar
https://raw.githubusercontent.com/myusername/myrepo/main/My%20API.bar

        (You’ll need to have a configuration object of type BarAuth that contains credentials for connecting to the endpoint.)

        Tip: If you provided a single BAR file for deployment earlier from the Integrations view, the BAR file is automatically stored in the Dashboard's content server and the generated location is displayed in the Advanced: Bar URL field.
        
      • Specify any other advanced settings that you require. If you need help with completing these fields, see the corresponding parameter descriptions for these fields in App Connect Integration Server reference: Custom resource values:

        Field	Parameter
        Advanced: Log Format	spec.logFormat
        Advanced: Labels (Applies custom labels to the deployment)	spec.labels
        Advanced: Labels (Applies custom labels to the integration server's HTTPS flows route)	spec.router.https.labels
        Advanced: Labels (Applies custom labels to a second route for the integration server's HTTPS flows)	spec.router.https2.labels
        Advanced: Annotations	spec.annotations
        Advanced: Default App Name	spec.defaultAppName
        Advanced: Disable Routes	spec.disableRoutes
        Advanced: AdminTLS	spec.adminServerSecure
        Advanced: Create Dashboard Users	spec.createDashboardUsers
        Advanced: Enable Metrics	spec.enableMetrics
        Runtime Container Tip: These fields can be used in place of the Advanced: Bar URL field and enable you to specify details of a custom server runtime image that you want to deploy to the integration server.	spec.pod.containers.runtime.*
        Hostname of the https flows route for the Integration Server (Adds a route)	spec.router.https.host
        Hostname of the https flows route for the Integration Server (Adds a second route)	spec.router.https2.host
        Timeout for the OpenShift router	spec.router.timeout
        Service	spec.service.*

   3. Click YAML editor to switch to code view for a more advanced configuration of fields that are not exposed in the Common settings view.
      • You can manually change the values of the parameters, which represent the fields in the Common settings view. Any changes that you make will be reflected in the Common settings view.
      • To see the full set of parameters that you can specify, go to App Connect Integration Server reference: Custom resource values.

      
   4. Click Create to create the integration server.
      The integration server is displayed as a tile on the Servers page of the dashboard, with an initial status of Pending (), which then changes to Ready when the deployment completes. To see the change in status, either click the Refresh icon on the page, or use the browser's refresh mechanism to reload the page.

      

      You can click the integration server tile to view the deployed integration. (For an API flow, this includes a single API and other resources that are defined in the uploaded BAR file.) From the tabs that are displayed, you can view details about the configured properties, policy projects, and endpoints.

      

      From the Servers page, you can also view the integrations for all listed integration servers by clicking Integrations to open the Integrations page.

      

      A configuration object of type REST Admin SSL files is automatically created and applied to the integration server to provide self-signed TLS certificates for secure communication between the App Connect Dashboard and the integration server. This configuration object is created from a predefined ZIP archive, which contains a set of PEM files named ca.crt.pem, tls.crt.pem, and tls.key.pem. A secret is also auto generated to store the Base64-encoded content of this ZIP file. This configuration object is added to the Configuration page with an assigned name of integrationServerName-is-adminssl, where integrationServerName is the metadata.name value for the integration server. For more information about this configuration type, see REST Admin SSL files type.

   Note: If you are using a Kubernetes environment, ensure that you create an ingress definition after you create this instance, to make its internal service publicly available. For more information, see Creating ingress definitions for external access to your IBM App Connect instances.
   Tip:

   • If required, you can deploy the same BAR file more than once to accommodate your workloads. A unique integration server must be created each time, typically with the same configurations. Different API endpoints are generated for each integration server.
   • From the Servers page of the dashboard, you can use the Share REST APIs feature to push (or export) the deployed API to IBM API Connect to take advantage of its advanced API management capabilities. For more information, see Pushing REST APIs to IBM API Connect by using the web user interface.