The BAR file for your exported flow contains all the resources that are needed to deploy
an integration that exposes the integration and its operations. To run this integration, you’ll need
to create an integration server to run the BAR file resources.
About this task
You can deploy one or more BAR files to an integration server by completing a
multi-step process:
- Use the App Connect Dashboard to upload the BAR file to a content server
in your cluster. If you intend to deploy one or more BAR files that are stored in an external
repository system, you can directly reference these files and do not need to upload them to the
content server.
- Use the Configuration component to create any configurations that you want to apply to the
integration server when you deploy it.
- Configure the integration server details. If you are deploying BAR files from an external
repository system, you must specify the location of the BAR files at this stage.
When the deployment completes, an integration server is created and started, and it reads
the BAR files to run the integration.
Important: When you use an App Connect Dashboard instance to create or access your integration servers, it is
advisable to maintain your Dashboard and integration servers at matching or compatible
(spec.version) versions. Attempting to use a Dashboard instance at an older
version to create or access an integration server at a later version might lead to incompatibility
issues.
Considerations for enabling tracing in the Operations Dashboard:
Applicable to Cloud Pak for Integration only: If you want to use the
Operations Dashboard add-on to provide cross-component transaction tracing to aid with
troubleshooting and latency issues in deployed integration servers, an instance of the Operations
Dashboard (Integration tracing) must be available in a specified namespace in your Cloud Pak for Integration environment. For information about creating an instance of
the Operations Dashboard, verifying the deployment, and configuring settings, see Operations Dashboard: Installation and Configuring Operations Dashboard
(integration tracing).
Transaction tracing for the integration servers in a namespace can be enabled only during
deployment as follows:
- To enable tracing data to be sent to the Operations Dashboard, a one-time registration request
must be completed in the Operations Dashboard.
- The registration process is activated the first time that an integration server is deployed with
tracing enabled (by setting Enable Operations Dashboard tracing to
on, and then setting Operations Dashboard namespace to
the namespace where the Operations Dashboard was created).
- When the deployment of the integration server is complete, open the Operations Dashboard
( in the navigation menu), navigate to the
Registration requests
page (under Manage in the
navigation pane), and then locate the Pending
registration request that was
automatically created.
- Approve the registration request and then run the supplied command to create a secret in the
namespace where the integration server is deployed. This secret will store the credentials that are
required to send tracing data to the Operations Dashboard.
For more information, see Capability registration and Registration requests.
- Deploy additional integration servers in the namespace with tracing enabled.
- Use the Operations Dashboard Web Console to view tracing data in preconfigured dashboards, view
distributed tracing information on a per-trace basis, generate reports and alerts, and manage
configuration settings. For more information, see Operations Dashboard Web Console
(integration tracing) guide.
If you do not have the required permissions to create an Operations Dashboard instance or approve
registration requests, you must work with your cluster or team administrator to complete these
steps.
Procedure
To create an integration server, complete the following steps:
- 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. You can click the tiles on this page to view any deployed integration servers from the
Servers tile, and their underlying integrations from the
Integrations tile (if shown). You can also create an integration server from
the Create a server tile, and view the documentation from the
Learn more tile.
- Complete either of the following steps depending on your location:
- From the Welcome page, click the Create a server
tile.
- 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 Create server.
- From the Type view on the
Create an Integration
Server
page, click one of the integration
tiles
to deploy an integration that you
obtained from any of these environments:
- 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 sizings
on the tiles for guidance.)
- Quick start integration
- Small integration
- Medium integration
- Large integration
- Click Next to proceed to the next stage.
- 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 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) Server
view.
- Click Next.
- 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 has
been configured to use a switch server for callable flow capability, and a Callable flow node was
configured in the exported flow, you'll require an Agentx file that enables connection to the switch
server. A preconfigured
default-agentx
entry is available in the configurations
table by default, and will be 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 will be
generated when you try to create the server.
- 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.
- 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 will include
configurations that were automatically created when the Designer instance was created. These
configurations will be prefixed with the name of the Designer instance. For example, if the Designer
instance is named des-01-quickstart
, you'll see configurations of various types
that are named in the format des-01-quickstart-designer-xxx
,
where xxx
represents an abbreviation of the configuration type.
Do not delete these configurations.
- Click Next.
- From the Server view, define details about the integration server
and install the BAR file resources:
- 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
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.
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:
Deprecated Select this option to use any combination of cloud-managed or local
connectors. This option will extend 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 will be 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 will be used. The operation will fail if the connection to the cloud-managed
connector also fails.
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.
- local: Select this option to use local connectors only. This option will
extend 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 will be used if a successful
connection can be established with the supplied credentials. Otherwise, the operation will
fail.
- 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 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.
- 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, as described in the About this task section.
- Operations Dashboard namespace: Specify the namespace where the
Operations Dashboard (Integration tracing) was deployed. This field is displayed only when
Enable Operations Dashboard tracing is set to on.
- 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
(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.* |
- Click YAML editor to switch to code view for a more advanced
configuration of fields that are not exposed in the Common settings
view.
- 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. (Refresh the page to see the change in status.)
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
Servers page, you can also view the integrations for all listed integration
servers by clicking Integrations to open the
Integrations page.
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 will be 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.