Installing and Operating Fuse Online on OpenShift Container Platform

Red Hat Fuse 7.11

Install, configure, and upgrade Fuse Online, and export/import integrations for CI/CD pipelines

Red Hat Fuse Documentation Team

Abstract

Information and instructions for installing, managing, and operating Fuse Online on OpenShift Container Platform in a customer-managed environment on-site, in the cloud, or in a hybrid cloud.

Preface

You can install and operate Fuse Online on-site on OpenShift Container Platform (OCP). When Fuse Online is running on-site, additional features are available beyond the features that are provided when Fuse Online is running on OpenShift Dedicated.

The term on-site means a customer-managed environment; Red Hat is not managing the OpenShift environment. A customer-managed environment can be on-premise, in the cloud, or in a hybrid cloud.

See the following topics for details:

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright’s message.

Chapter 1. Installing Fuse Online on OCP 4.x

Fuse Online is a flexible and customizable, open source platform that provides core integration capabilities as a service.

Each installation of Fuse Online is referred to as a Fuse Online instance (or environment). In a given OpenShift project, there can be exactly one Fuse Online instance. Each Fuse Online instance has its own URL. In a single OpenShift cluster, there can be multiple Fuse Online instances.

You can install Fuse Online as an OpenShift developer user if you have the proper permissions to install operators from OperatorHub. You can install a default Fuse Online instance or a customized Fuse Online instance. For a customized Fuse Online instance, you must edit the default custom resource.

Important

The Fuse Online installation process requires access to registry.redhat.io, which is the Red Hat Ecosystem Catalog for container images.

The following topics provide details for installing Fuse Online:

1.1. Overview of the steps required to install Fuse Online on OCP 4.x

To install Fuse Online on OCP 4.x, here are the main steps:

  1. Generate an OpenShift secret that configures authentication to Red Hat container images.
  2. Install the Fuse Online Operator from the OperatorHub to a project (namespace) on the cluster.
  3. Optionally, if you want to include an external database for persisting connection and integration definitions, create an OpenShift secret.
  4. Add a Fuse Online instance to an OpenShift 4.x project.

    Optionally, edit the custom resource to enable one or more add-on features and/or implement one or more custom configuration settings.

  5. Optionally, grant permission to other developer users so that they can access the Fuse Online web console.

1.1.1. Considerations for installing Fuse Online in a restricted environment (OCP 4.6 and later)

Before you install Fuse Online in a restricted environment, you must complete the following tasks.

Prerequisite

  • You have cluster admin access on the restricted environment’s OpenShift cluster.

Procedure

  • Mirror all of the Fuse Online images to a location available on your private network. For more information about installing images for OpenShift operators in a restricted environment, see the Using Operator Lifecycle Manager on restricted networks section in the OpenShift documentation.
  • Set up a custom Maven repository with the Fuse repository contents. For detailed information, see the Red Hat Solution: How to create an offline Maven repository for Fuse 7.
  • Before you install Fuse Online, edit the Fuse Online custom resource. Use the maven:mirror setting to instruct Fuse Online to only look at the single specified Maven repository to access Maven artifacts when it builds integrations.

    In the following example, replace https://customRepo with your offline repository’s URL:

    components:
      server:
        features:
          maven:
            mirror: https://customRepo
  • Set the HTTPS_PROXY, HTTP_PROXY, and NO_PROXY environment variables to syndesis-oauthproxy. You can set these environment values when you install Fuse Online or afterwards.

    To set the environment values on syndesis/app after you install Fuse Online:

    1. Retrieve the values from proxy/cluster by using the following commands:

      myhttpProxy=$(oc get proxy/cluster -ojsonpath='{.status.httpProxy}')
      
      myhttpsProxy=$(oc get proxy/cluster -ojsonpath='{.status.httpsProxy}')
      
      mynoProxy=$(oc get proxy/cluster -ojsonpath='{.status.noProxy}')
    2. Set the values by using the following oc patch command:

      oc patch syndesis/app --type=merge -p "{\"spec\": {\"components\": {\"oauth\": {\"environment\": {\"HTTPS_PROXY\": \""${myhttpsProxy}"\", \"HTTP_PROXY\": \"${myhttpProxy}\", \"NO_PROXY\": \"${mynoProxy}\"}}}}}"

      This command returns the following confirmation:

      syndesis.syndesis.io/app patched

      Because you changed the syndesis-oauthproxy deployment, OpenShift recreates the syndesis-oauthproxy-1-deploy pod.

  • By default, the todo sample application is disabled (in the Fuse Online custom resource, the addon:todo:enabled value is set to false). Optionally, after you install Fuse Online in a restricted environment, you can download the todo sample application from https://github.com/syndesisio/todo-example and follow the steps in the Readme file, changing the repository URL to the location available on your private network.

1.2. When editing the default custom resource is required before installing Fuse Online

The Fuse Online installation includes a default custom resource, which specifies the default settings for configurable Fuse Online environment add-on features and parameter settings.

You need to edit the default custom resource before you install Fuse Online if you want the installed Fuse Online environment to:

  • Use a URL that you specify for the OpenShift route by which the Fuse Online console can be reached. The default is that the installation process calculates this route.
  • Use an external database to store connection and integration definitions. The default is that the environment uses an internal database.
  • Increase the amount of internal storage that is available for persisting connection and integration definitions. The default, which is 1Gi, is sufficient for most Fuse Online environments.

To configure a Fuse Online environment for any one of these behaviors, you MUST edit the custom resource when you install Fuse Online. In other words, you cannot change the configuration of an installed Fuse Online environment to implement any of these behaviors. Also, after you install a Fuse Online environment that is configured for any of these behaviors, you cannot change that behavior in the installed environment.

1.3. Descriptions of custom resource attributes that configure Fuse Online

In addition to the custom resource attributes that you can specify only before installation, there are a number of custom resource attributes that you can change before or after installation.

Table 1 provides a brief description of configurable custom resource settings and indicates when you can change them: before and/or after installation. To achieve the Fuse Online configuration that you want, use the information in this table to determine how you need to change the custom resource before installation or how you want to change it after installation. Then follow the appropriate procedure:

For OCP 4.x:

Table 1.1. Configurable custom resource settings

Feature/SettingWhen you can set thisSpecification

Enhanced activity tracking

Additional information about enhanced activity tracking follows this table.

Set only before installation

addons:
  jaeger:
    enabled: true
    clientOnly: false
    operatorOnly: false

Enhanced activity tracking is enabled, by default. If you want to customize the Jaeger configuration, you can set clientOnly or operatorOnly to true.

External database

Additional information about using an external database follows this table.

Set only before installation

spec:
  components:
    database:
      externalDbURL: postgresql://custom-postgres:5432
      user: db-user-name
      name: db-name


Replace custom-postgres:5432 with the host name and port for a PostgreSQL database.
Replace db-user-name with the name of a user account that can access that database.
Replace db-name with the name of the database.

Internal storage capacity for connections and integrations.

Ignored if you also specify an external database.

Additional information about increasing internal storage follows this table.

Set only before installation

spec:
  components:
    database:
      resources:
        volumeCapacity: 1Gi
        volumeName: my-volume


Replace 1Gi with the amount of storage you need. The default is 1Gi.

Replace my-volume with the name of the volume to use for internal storage. This parameter is optional.

OpenShift route for accessing Fuse Online console

Set only before installation

spec:
  routeHostname: project.route.com


Replace project.route.com with the OpenShift route by which the Fuse Online console can be reached.
For example: north-project.6a63.fuse-online.openshiftapps.com

Memory and CPU

Increase the default amount of memory that is available to one or more components.

Each component defines its own memory requirement, which means that each pod has a limit on the amount of memory it is assigned. For information about limit and request settings, see the section on Configuring cluster memory to meet container memory and risk requirements in the OpenShift documentation.

You can also specify CPU resources for the server component.

The database component is the internal database that stores connection and integration definitions.

The meta component provides the business logic, such as the connectors, which the server loads.

The prometheus component monitors Fuse Online infrastructure components and Fuse Online integrations.

Set only before installation

components:
  server:
    resources:
      limit:
        memory: "1024Mi"
        cpu: "800m"
      request:
        memory: "512Mi"
        cpu: "500m"
  meta:
    resources:
      limit:
        memory: "750Mi"
      request:
        memory: "300Mi"
  database:
    resources:
      limit:
        memory: "300Mi"
      request:
        memory: "300Mi"
  prometheus:
    resources:
      limit:
        memory: "750Mi"
      request:
        memory: "750Mi"

3scale discovery

Expose APIs for Fuse Online API provider integrations so that they are discoverable by Red Hat 3scale.

More information: Configuring Fuse Online to enable 3scale discovery of APIs.

Set before or after installation

components:
    server:
      features:
        managementUrlFor3scale: https://url-for-3scale


Specify the URL for your 3scale user interface.

Backups

Additional setup steps are described in Backing up a Fuse Online environment.

Set before or after installation

spec:
  backup:
    schedule: interval


Replace interval with the desired duration between backups. Use cron utility format for intervals and predefined schedules. Do not specify the @ sign in front of the interval.

Node affinity and tolerations

Determines the placement of Fuse Online infrastructure component and integration pods onto nodes within the cluster.

Node affinity allows you to specify an affinity for Fuse Online pods towards a group of nodes to be placed on.

Tolerations allows you to control which nodes the Fuse Online pods run on and to prevent other workloads from using those nodes.

See also: Configuring Fuse Online pods.

Set before or after installation

Note: Use infraScheduling for Fuse Online infrastructure component deployments. For Fuse Online integration deployments, replace infraScheduling with integrationScheduling.

spec:
  infraScheduling:
    tolerations:
      key: value
      operator: value
      effect: value


spec:
  infraScheduling:
    affinity:
      nodeAffinity:
        preferredDuringSchedulingIgnoredDuringExecution:
          weight:
          preference:
            matchExpressions:
              key: value
              operator: value
              values:
                value1,
                value2

Integration limit

Specify the maximum number of running integrations. The default, 0, does not limit the number of running integrations.

Set before or after installation

components:
    server:
      features:
        integrationLimit: 0

Database connection pool

You can adjust the server connection pool configuration to manage the connections to the database.

Additional information about the database pool configuration follows this table.

Set before or after installation

components:
  server:
    connectionPool:
      connectionTimeout: 30000
      idleTimeout: 600000
      leakDetectionThreshold: 0
      maxLifetime: 1800000
      maximumPoolSize: 10
      minimumIdle: 10

Java Options

You can specify Java options for the syndesis-server and syndesis-meta components.

Depending on the Java option, you can specify different values for the components. For example, you can set a JVM-related parameter for syndesis-server only, because it requires more computer resources than syndesis-meta.

Set before or after installation

components:+   server:
    javaOptions:
      -option_name=my_value   meta:
    javaOptions:
      -option_name=my_value

Replace -option_name with the Java option name. You can specify any Java option prefix (-D, -X, or -XX).

Replace my_value with value for the option.

For example, to configure the HTTP proxy: components:+   server:
    javaOptions:
      -Dhttp.proxyHost=10.0.0.100 -Dhttp.proxyPort=8800   meta:
    javaOptions:
      -Dhttp.proxyHost=10.0.0.100 -Dhttp.proxyPort=8800`

Maven Arguments

Specify additional Maven options to use when building Fuse Online integrations.

Set before or after installation

components:
    server:
      features:
        maven:
          additionalArguments:
            "typeA=stringA typeB=stringB"


For example:
          additionalArguments:
            "-Dhttp.proxy=my_proxy -DpropA=valueA"

Maven Mirror

Specify the single repository from which you want Fuse Online to access Maven artifacts when it builds integrations. Ignore the Maven repositories that Fuse Online would access by default. This option is typically used when you install Fuse Online in a restricted environment.

Set before or after installation

components:
    server:
      features:
        maven:
          mirror: https://customRepo

Replace `https://customRepo
with the URL of the repository.

Maven Repositories

Specify external Maven repositories that your Fuse Online environment needs to access, in addition to the Maven repositories that Fuse Online accesses by default.

Set before or after installation

components:
    server:
      features:
        mavenRepositories:
          customRepo1: https://customRepo1
          customRepo2: https://customRepo2


Replace customRepo with the name of a repository.
For each repository, specify its URL.

Monitoring

See also: Monitoring Fuse Online integrations on OCP with Prometheus.

Set before or after installation

addons:
  ops:
    enabled: true

Public REST API

Additional set-up steps are described in Exposing Fuse Online public REST API endpoints for use by external tools.

Set before or after installation

addons:
  publicApi:
    enabled: true
    routeHostname: public-syndesis.192.168.64.63.nip.io


Set routeHostname to the public address for invoking Fuse Online REST API endpoints. Your cluster setup determines the public address that you need to specify. In the previous example, the route host name is valid for a minishift cluster.

ToDo addon
Provides a sample integration application for testing purposes, an AMQ Broker, as well as a sample PostgreSQL database and a sample database connector.

Set before or after installation

spec:
  addons:
    todo:
      enabled: false

For installing Fuse Online in a restricted environment, you must make sure that the todo addon is set to false (the default) before installation. After installing Fuse Online , you can optionally download the todo application from https://github.com/syndesisio/todo-example and follow the steps in the Readme file, changing the repository URL to a location available on your private network.

See also Adding sample data to a Fuse Online environment running on OCP.

Auditing

For viewing basic changes made to connectors, connections, and integrations.

See also Auditing Fuse Fuse Online components.

Note: This is a Technology Preview feature.

Set before or after installation

components:
  server:
    features:
      auditing: true

About add-on features and configuration settings

  • Enhanced activity tracking

    Activity tracking, using Jaeger, is enabled by default when you install Fuse Online. The Fuse Online installation (from the OperatorHub or the command-line script) detects the existence of the OperatorHub and installs Jaeger by using the OperatorHub’s subscription functionality. For the limited circumstances in which the OperatorHub is not available, Fuse Online uses its own installation functions to install Jaeger. Optionally, you can customize the Jaeger configuration before you install Fuse Online as described in the About configuring Fuse Online for Jaeger monitoring section.

  • External database for persisting connections and integrations

    A default installation of Fuse Online provides an internal PostgreSQL database that Fuse Online uses to persist connection and integration definitions. You can choose to use an external PostgreSQL database instead, such as one of the PostgreSQL templates that OpenShift provides by default.

  • Internal storage capacity

    The default setting of 1Gi is sufficient for most Fuse Online environments. It is expected that you would increase this setting for a new Fuse Online installation only upon the recommendation of Red Hat technical support. That is, you have been running another Fuse Online environment in which you encountered Fuse Online server errors and Red Hat technical support determined that you need to install a new Fuse Online environment with a database volume capacity that is larger than the default.

    To increase Fuse Online internal storage capacity in an OpenShift project that is already running Fuse Online, you must first uninstall Fuse Online. See Uninstalling Fuse Online from an OCP project.

  • Database connection pool configuration

    You can configure the following syndesis-server database connection pool properties:

    • connectionTimeout - The maximum number of milliseconds that the syndesis-server waits for a connection from the pool. The lowest acceptable connection timeout is 250 ms. The default is 30000 (30 seconds).
    • idleTimeout - The maximum amount of time (in milliseconds) that a connection is allowed to sit idle in the pool before the connection is removed. A value of 0 means that idle connections are never removed from the pool. The minimum allowed value is 10000 (10 seconds). The default is 600000 (10 minutes),
    • leakDetectionThreshold - The amount of time (in milliseconds) that a connection can be out of the pool before a message is logged indicating a possible connection leak. A value of 0 means leak detection is disabled. The lowest acceptable value for enabling leak detection is 2000 (2 seconds). The default is 0.
    • maxLifetime - The maximum lifetime (in milliseconds) of a connection in the pool. The minimum allowed value is 30000 (30 seconds). The default is 1800000 (30 minutes).
    • maximumPoolSize - The maximum size that the pool is allowed to reach, including both idle and in-use connections. The default is 10.
    • minimumIdle - The minimum number of idle connections maintained in the pool. The default is the value of maximumPoolSize.

1.4. About configuring Fuse Online for Jaeger monitoring

Jaeger is open source software for tracing transactions between distributed services. It is especially useful for monitoring and troubleshooting complex microservices environments.

When you install Fuse Online, either from the OperatorHub or by using the command-line script, the Fuse Online installation detects the existence of the OperatorHub and installs Jaeger by using the OperatorHub’s subscription functionality. For the limited circumstances in which the OperatorHub is not available, Fuse Online uses its own installation functions to install Jaeger.

A default Fuse Online environment configures all needed Jaeger components. Optionally, you can edit the Fuse Online custom resource to specify a client-only/independent server configuration or a hybrid Jaeger client and Jaeger Operator configuration.

Default Jaeger configuration

The basic, out-of-the-box, configuration includes all Jaeger components. You can start learning about how Jaeger works by experimenting with its monitoring capabilities. The default configuration provides a memory-only, limited, backend storage capability.

Installing Fuse Online with the default Jaeger configuration has the following results:

  • Fuse Online components have Jaeger communication URLs.
  • Jaeger Operator is installed.
  • Jaeger custom resource is configured with a default configuration for activity monitoring.

A Fuse Online installation with the default Jaeger configuration, has the following syndesis custom resource specification:

apiVersion: syndesis.io/v1beta2
kind: Syndesis
metadata:
  name: app
spec:
  addons:
    jaeger:
      enabled: true

When the clientOnly and operatorOnly are unspecified (set to false, by default) Fuse Online uses the provided Jaeger backend as well as the default, memory-only storage provided by the Jaeger server configuration.

Client-only/independent server configuration

With a client-only/independent server configuration, only client URL connections are configured for communication between Fuse Online and an externally configured Jaeger backend. All aspects of the Jaeger backend are external and independent of the Fuse Online environment and syndesis-operator. This includes the Jaeger Operator and the Jaeger custom resource.

To install a client-only Jaeger configuration, edit the custom resource before you install Fuse Online as follows:

For example:

apiVersion: syndesis.io/v1beta2
kind: Syndesis
metadata:
  name: app
spec:
  addons:
    jaeger:
      enabled: true
      clientOnly: true
      queryUri: https://jaeger-query-hostname:443/api
      collectorUri: https://jaeger-collector-hostname:14268/api/traces

Hybrid Jaeger client and operator configuration

With a hybrid Jaeger client and Jaeger Operator configuration, Fuse Online installs the Jaeger Operator as well as the Jaeger client capabilities. A Jaeger custom resource is not installed. You must install your own Jaeger custom resource, which defines your Jaeger server configuration. This lets you take advantage of the Fuse Online-provided capability and also tailor Jaeger configuration for your own environment, for example, you can use Elasticsearch or Cassandra for data storage.

To install a hybrid Jaeger client and Jaeger Operator configuration:

  • Edit the custom resource before you install Fuse Online as shown in the following example:

    apiVersion: syndesis.io/v1beta2
    kind: Syndesis
    metadata:
      name: app
    spec:
      addons:
        jaeger:
          enabled: true
          operatorOnly: true
  • Name the Jaeger custom resource syndesis-jaeger as shown in the following example:

    apiVersion: jaegertracing.io/v1
    kind: Jaeger
    metadata:
      name: syndesis-jaeger
      ...
    spec:
       ....

    Note: Alternately, if you want to use a different name for the Jaeger custom resource, set the queryUri and collectorUri in the Syndesis custom resource as described in the Client-only/independent server configuration section.

When the Jaeger custom resource with syndesis-jaeger name is created, the Jaeger instance collects data from the Fuse Online integrations. By default, you can view this data in the Fuse Online activity log.

1.5. Installing Fuse Online with an external database

If you want to install a Fuse Online environment that uses an external database to persist connection and integration definitions:

  • Create a postgreSQL database with a hostname that the OpenShift cluster can locate.
  • Before you install Fuse Online, create an OpenShift secret named syndesis-global-config for the external database.
  • Install Fuse Online.
  • Before you deploy Fuse Online, edit the custom resource to configure the connection to the external database.

Prerequisites

  • Fuse Online is not yet installed.
  • The oc client tool is installed and it is connected to the OCP cluster in which you plan to install Fuse Online.
  • A user with cluster administration permissions gave you permission to install Fuse Online in any project that you have permission to access in the cluster.

Procedure

  1. Log in to OpenShift with an account that has permission to install Fuse Online. For example:

    oc login -u developer -p developer
  2. Create a postgreSQL database that is available to the OpenShift cluster on which you install Fuse Online and that defines values for the following configuration options:

    • Connection username
    • Database name
    • Database password

      The following example uses one of the PostgreSQL templates that OpenShift provides by default.

      Note: Only use the PostgreSQL ephemeral (postgresql-ephemeral) template for development or testing purposes. For a production environment, use the PostgreSQL (postgresql) template.

      oc new-app postgresql-ephemeral -p POSTGRESQL_USER=syndesis -p POSTGRESQL_PASSWORD=exdb-pwd -p POSTGRESQL_DATABASE=syndesisdb

      This command returns information about the database that you need when you configure Fuse Online, such as the URL.

      For information about creating a database see the PostgreSQL topic in the OpenShift documentation.

  3. Create and save a resource file (for example, my-fuse-online-secret-cr.yml) that contains the following content:

    apiVersion: v1
    kind: Secret
    metadata:
      name: syndesis-global-config
      namespace: my-fuse-online-project
    type: Opaque
    stringData:
      POSTGRESQL_PASSWORD: exdb-pw

    Replace my-fuse-online-project with the name of the OpenShift project in which you plan to install the Fuse Online environment for which you are specifying an external database.

    Replace exdb-pw with the password from Step 2. Fuse Online will use it as the password for accessing the external database. Note that stringData converts the password value to a base64-encoded value (so that you do not have to do the conversion).

    For information about OpenShift secrets, see Providing sensitive data to pods.

  4. Add the secret to the cluster, for example:

    oc apply -f my-fuse-online-secret-cr.yml

    On the OpenShift cluster, the syndesis-global-config secret is available to a Fuse Online environment that is installed with a custom resource that specifies an external database.

  5. Install Fuse Online in the my-fuse-online-project project that you specified in the YAML file for the secret (in Step 4).

    • For OCP 4.6 and later, follow the instructions in Installing the Fuse Online Operator from the OperatorHub. In Adding a Fuse Online instance to an OpenShift 4.x project, before you deploy Fuse Online, edit the custom resource to specify the use of an external database, for example:

      apiVersion: syndesis.io/v1alpha1
      kind: Syndesis
      metadata:
        name: app
      spec:
        components:
          database:
            externalDbURL: "postgresql://syndesis-external-db:5432"
            user: db-user-name
            name: db-name
    • Replace syndesis-external-db:5432 with the host name and port for the external PostgreSQL database.
    • Replace db-user-name with the Connection username.
    • Replace db-name with the name of the database.

Result

The Fuse Online installation process uses the settings in the custom resource to determine the configuration of the installed Fuse Online environment.

When correctly installed and deployed, Fuse Online brings up all of the required pods except for syndesis-db. Instead of syndesis-db, the syndesis-server connects to the database with the service name of the external database. If the external database configuration is incorrect then the syndesis-server fails to initialize and the Fuse Online deployment ends with an error.

1.6. Installing Fuse Online

Fuse Online is a flexible and customizable, open source platform that provides core integration capabilities as a service. You can install Fuse Online as an OpenShift developer user if you have the proper permissions to install operators from OperatorHub.

Here are the general steps for installing Fuse Online by using the operator:

  1. Create a secret in the OpenShift project (namespace) to configure authentication with registry.redhat.io so that the Fuse Online Operator can access the necessary installation templates.
  2. Install the Fuse Online Operator to an OpenShift project (namespace). When the operator is installed, the operator is running in the selected namespace.
  3. Create an instance of Fuse Online from the installed operator. You can create an instance with default settings or you can customize the instance by editing the instance’s custom resource. You can then access Fuse Online from the provided URL.

The following topics provide details for installing Fuse Online on OCP 4.x by using the operator:

1.6.1. Authenticating with registry.redhat.io for container images

Configure authentication with registry.redhat.io before you can deploy Fuse container images on OpenShift.

Prerequisites

  • Cluster administrator access to an OpenShift Container Platform cluster.
  • OpenShift oc client tool is installed. For more details, see the OpenShift CLI documentation.

Procedure

  1. Log into your OpenShift cluster as administrator:

    oc login --user system:admin --token=my-token --server=https://my-cluster.example.com:6443
  2. Open the project in which you want to deploy Fuse:

    oc project myproject
  3. Create a docker-registry secret using your Red Hat Customer Portal account, replacing PULL_SECRET_NAME with psi-internal-registry to create:

    oc create secret docker-registry psi-internal-registry \
      --docker-server=docker-registry.redhat.io \
      --docker-username=CUSTOMER_PORTAL_USERNAME \
      --docker-password=CUSTOMER_PORTAL_PASSWORD \
      --docker-email=EMAIL_ADDRESS

    You should see the following output:

    secret/psi-internal-registry created
    Important

    You must create this docker-registry secret in every OpenShift project namespace that will authenticate to registry.redhat.io.

  4. Link the secret to your service account to use the secret for pulling images. The following example uses the default service account, builder service account, and deployer service account:

    oc secrets link default psi-internal-registry
    oc secrets link default psi-internal-registry --for=pull
    oc secrets link builder psi-internal-registry
    oc secrets link builder psi-internal-registry --for=pull
    oc secrets link deployer psi-internal-registry
    oc secrets link deployer psi-internal-registry --for=pull

    The service account name must match the name that the OpenShift pod uses.

    Note

    If you do not want to use your Red Hat username and password to create the pull secret, you can create an authentication token using a registry service account.

Additional resources

For more details on authenticating with Red Hat for container images:

1.6.2. Installing the Fuse Online Operator from the OperatorHub

You can install the Fuse Online Operator from OperatorHub by using the OpenShift Container Platform web console. Follow these steps for each OpenShift project (namespace) in which you want to install Fuse Online.

Prerequisites

  • You have administrator or developer access to the OpenShift cluster. For a developer user, you have proper permissions to install operators from OperatorHub.
  • You have configured authentication with registry.redhat.io as described in Authenticating with registry.redhat.io for container images.
  • You installed the oc client tool and it is connected to the OCP cluster on which you plan to install Fuse Online.

Procedure

  1. In a web browser, navigate to the OpenShift console in your browser and then log in to the console with your administrator or developer credentials.
  2. If you are logged in as an administrator, click Operators and then click OperatorHub.

    If you are logged in as a developer, click Add and then click the From Catalog card.
  3. In the Filter by keyword field, type Fuse Online.
  4. Click the Red Hat Integration - Fuse Online card. The Fuse Online Operator install page opens.
  5. Click Install. The Install Operator page opens.

    1. The Update Channel defines a stream of updates for the operator and is used to roll out updates for subscribers. Accept the default channel, latest.
    2. For Installation mode, select a namespace (project) from the list of namespaces on the cluster. Select the same namespace that you used when you created a docker registry secret in Authenticating with registry.redhat.io for container images.
    3. For the Update Approval, select Automatic or Manual to configure how OpenShift handles updates to the Fuse Online Operator.

      • If you select Automatic updates, when a new version of the Fuse Online Operator is available, the OpenShift Operator Lifecycle Manager (OLM) automatically upgrades the running instance of the Fuse Online without human intervention.
      • If you select Manual updates, when a newer version of an operator is available, the OLM creates an update request. A cluster administrator must then manually approve that update request to have the Fuse Online Operator updated to the new version.
  6. Click Install to make the Fuse Online Operator available in the specified namespace (project).
  7. To verify that Fuse Online is installed in the project, click Operators and then click Installed Operators to see Red Hat Integration - Fuse Online in the list.
  8. In a Terminal window, type the following command to link the secret (that you created in Authenticating with registry.redhat.io for container images) to the Fuse Online Operator service account:

    oc secrets link syndesis-operator PULL_SECRET_NAME --for=pull

Next Steps

After the Fuse Online Operator is installed, you add an instance of Fuse Online to the OpenShift project.

1.6.3. Adding a Fuse Online instance to an OpenShift 4.x project

After the Fuse Online Operator is installed in an OpenShift 4.x project, you add an instance of Fuse Online to the OpenShift project. The Fuse Online instance provides the URL that a developer uses to access Fuse Online.

Prerequisites

  • The Fuse Online Operator is installed into the current OpenShift project.
  • On your OCP environment, at least three persistent volumes are available for use by Fuse Online. All of the persistent volumes must have the following configuration requirements:

    • capacity.storage: 1Gi
    • accessMode: ReadWriteOnce
  • Decide if you want to install a default Fuse Online instance or customized instance. For more information about the custom resource settings that you can specify, see When editing the default custom resource is required before installation.

Procedure

  1. Follow these steps to access the Create Syndesis page depending on your user role:

    • If you are logged in as an administrator:

      1. Click Operators and then click Installed Operators.
      2. In the Name column, click Red Hat Integration - Fuse Online. The Operator Details page opens.
      3. Under Provided APIs, click Create Instance.
    • If you are logged in as a developer:

      1. Click Add and then click the Operator Backed card.
      2. Click the Syndesis CRD card. The Syndesis CRD page opens.
      3. Click Create.

        The Create Syndesis page opens.
  2. Enter a name or leave app as the default.
  3. Select the YAML view option to view the default custom resource.
  4. Optional. Edit the custom resource.

    For details on the custom resource settings that you can specify see When editing the default custom resource is required before installation and Descriptions of custom resource attributes that configure Fuse Online.

    The Fuse Online installation process uses the settings that you specify in the custom resource to determine the configuration of the installed Fuse Online environment.

  5. Click Create to create the Fuse Online instance. OpenShift starts the pods, services, and other components for Fuse Online.
  6. To obtain the URL for Fuse Online:

    1. Click Networking > Routes.
    2. Make sure that the correct project is selected.
    3. In the syndesis row, in the Location column, click the URL for Fuse Online.
    4. Use your OpenShift login credentials to login to the Fuse Online environment.
  7. To allow other developer users access to the Fuse Online web console, an administrator must grant each developer user the view role for the project in which Fuse Online is installed by using the following command:

    oc adm policy add-role-to-user view <username> -n <project-name>

    For example, to grant view permission for the myfuseonline project to user jdoe:

    oc adm policy add-role-to-user view jdoe -n myfuseonline

Chapter 2. Changing the configuration of a Fuse Online environment

After you install Fuse Online on OpenShift Container Platform (OCP) on-site, you can change the configuration of the Fuse Online environment.

See the following topics for details:

2.1. Fuse Online configuration changes allowed after installation

After you install Fuse Online on OpenShift Container Platform (OCP) on-site, you can change its configuration to enable/disable some features or change some configuration settings. The following table lists the features and settings that you can change, the effect of the change, and where to find instructions for making the change.

When changes to the syndesis custom resource cause redeployment of syndesis-server, OpenShift creates a new server pod. It takes a maximum of one to two minutes until the new server is ready. During this time, the Fuse Online console is not usable. Integrations that are running continue to run while a new server is being deployed. When the new deployment is ready, the new server loads the state of the integrations. You can use the Fuse Online console again when the syndesis-server pod status is Running and refreshing the Fuse Online console displays values for integrations, connections, messages, and uptime.

Table 2.1. Features and settings that you can change

Feature/SettingEffect of changingInformation

3scale discovery

Redploys syndesis-server

Configuring Fuse Online to enable 3scale discovery of APIs

Backups

Adds a backup job to syndesis-operator

Backing up a Fuse Online environment

Auditing

Note: This is a Technology Preview feature.

Updates the configuration of the running syndesis-server. No redeployment is needed.

Auditing Fuse Fuse Online components

Monitoring

Installs new OpenShift resources

Monitoring Fuse Online integrations on OCP with Prometheus

Public Fuse Online REST API endpoints

Creates syndesis-public-oauthproxy pod

Exposing Fuse Online public REST APIs for use by external tools

Sample Todo app, AMQ Broker, sample PostresSQL database and connector

The todo addon creates a new todo pod for the sample Todo app for testing integrations. It also provides an AMQ Broker as well as a sample database and sample database connector. It creates a PostgreSQL database named sampledb and adds a PostgresDB Connection to SampleDB connector in the Fuse Online environment.

Note that changing the todo addon option triggers redeployment of the syndesis-server and sydnesis-db pods.

Adding sample data to a Fuse Online environment running on OCP

Descriptions of custom resource attributes that configure Fuse Online

Java options

Redeploys syndesis-server

Descriptions of custom resource attributes that configure Fuse Online

Configuring the HTTP proxy

Maven configuration

You must delete the syndesis-server pod to trigger its redeployment.

Assigning Fuse Online pods to OpenShift cluster nodes

Redeploys Fuse Online infrastructure component and integration pods

Descriptions of custom resource attributes that configure Fuse Online

Configuring Fuse Online pods

Memory available to Fuse Online components

Redeploys component with changed memory

Descriptions of custom resource attributes that configure Fuse Online

Number of running integrations allowed

You must delete the syndesis-server pod to trigger its redeployment.

Database connection pool

Redploys syndesis-server

2.2. General procedure for changing Fuse Online configuration

For a Fuse Online environment that is installed on OCP, you can change its configuration by updating its syndesis custom resource. After you save your changes, OpenShift updates syndesis-operator with your updates if they are syntactically correct. A syntax error prevents the update.

While editing the syndesis custom resource, ensure that you do not specify an invalid setting that is syntactically correct. The syndesis-operator will use the updated syndesis custom resource even if a syntactically correct setting is invalid. If you do specify an invalid setting, you learn about it only after OpenShift completes the update. During the update, OpenShift deletes invalid settings.

Prerequisites

  • Fuse Online is installed on OCP on-site.
  • The oc client tool is installed and it is connected to the OCP cluster in which Fuse Online is installed.
  • You have permission to install Fuse Online in the project for which you want to change Fuse Online configuration.
  • You consulted Descriptions of custom resource attributes that configure Fuse Online to learn which configuration changes are allowed after installation and how to update the syndesis custom resource for the configuration changes you want to make.

Procedure

  1. Log in to OpenShift with an account that has permission to install Fuse Online. For example:

    oc login -u developer -p developer

  2. Switch to the OpenShift project that is running the Fuse Online environment whose configuration you want to change. For example:

    oc project my-fuse-online-project

  3. Optional. Create a backup copy of the current settings in the syndesis custom resource, just in case you update and save incorrect content. For example, invoking the following command saves a backup in the syndesis_app_backup.yml file:

    oc get syndesis app -o yaml > syndesis_app_backup.yml

  4. Invoke the following command to open the syndesis custom resource in an editor:

    oc edit syndesis/app

    Note: This procedure describes how to set configurations by opening the custom resource file in an editor. Alternatively, you can use oc patch commands to edit the custom resource.

  5. Edit the syndesis custom resource as needed.
  6. Save the resource.

    Depending on the type of object that your edits apply to, your update triggers the syndesis-operator to redeploy some Fuse Online components when you save the resource.

  7. Wait two or three minutes, and then confirm that the syndesis custom resource was updated correctly:

    1. Invoke the following command to display the content of the syndesis custom resource:

      oc describe syndesis/app

    2. Check the content.

      If the syndesis custom resource does not contain the settings that you need, edit it again to specify valid settings.

Results

Most changes to the syndesis custom resource trigger syndesis-operator to redeploy the Fuse Online syndesis-server component. This means that OpenShift creates a new server pod.

It takes a maximum of one to two minutes until the new server is ready. During this time, the Fuse Online console is not usable. Integrations that are running continue to run while a new server is being deployed. When the new deployment is ready, the new server loads the state of the integrations. You can use the Fuse Online console again when:

  • The syndesis-server pod status is Running.
  • Refreshing the Fuse Online console displays values for integrations, connections, messages, and uptime.

Some changes to the syndesis custom resource update the Fuse Online configuration but do not require redeployment of syndesis-server. For example:

  • When you update the syndesis custom resource to specify backups, it is a few seconds before the backup job is in place.

The effect of each configuration change is described in Fuse Online configuration changes allowed after installation.

2.3. Configuring Fuse Online and 3scale discovery of APIs

If you create an API provider integration, you might want to enable discovery of the API for that integration in Red Hat 3scale. The default behavior is that APIs are not exposed for automatic discovery in 3scale.

If you enable 3scale discovery, you can later optionally disable it.

2.3.1. Configuring Fuse Online to enable 3scale discovery of APIs

If you create an API provider integration, you might want to enable discovery of the API for that integration in Red Hat 3scale. The default behavior is that APIs are not exposed for automatic discovery in 3scale. When you enable discovery, you must provide a URL for a 3scale user interface.

To configure Fuse Online to enable 3scale discovery of APIs before you install Fuse Online, see Descriptions of custom resource attributes that configure Fuse Online.

After installation, you can enable discovery by updating the syndesis custom resource. Instructions for doing this are in this topic. When you enable discovery, it applies to only the OpenShift project that you are connected to when you update the resource.

Turning on 3scale service discovery means that:

  • The default behavior is that 3scale publishes API provider integrations. When 3scale publishes an API provider integration:

    • Fuse Online does not provide an external URL for an API provider integration that is running.
    • The API is accessible only through 3scale. Configuration in 3scale is required to expose the endpoint. For details, see Red Hat 3scale API Management, Service Discovery.
  • The creator of an API provider integration can disable 3scale discovery for that integration. In other words, each API provider integration creator can choose whether that integration’s API is discoverable.

Prerequisites

  • Fuse Online is installed on OCP on-site.
  • The oc client tool is installed and it is connected to the OCP cluster in which Fuse Online is installed.
  • You have permission to install Fuse Online in the project for which you want to enable discovery of APIs.
  • You know the name of the 3scale project on the OpenShift cluster.

Procedure

  1. Log in to OpenShift with an account that has permission to install Fuse Online. For example:

    oc login -u developer -p developer

  2. Switch to an OpenShift project in which Fuse Online is running. You are enabling discovery for only this project. For example:

    oc project my-fuse-online-project

  3. Add permissions that allow the 3scale project to view Fuse Online integrations:

    oc adm policy add-cluster-role-to-user view system:serviceaccount:<3scale-project>:amp

    For example, if the 3scale project on OpenShift is named my3scale:

    oc adm policy add-cluster-role-to-user view system:serviceaccount:my3scale:amp

  4. Edit the syndesis custom resource:

    1. Invoke the following command, which typically opens the resource in an editor:

      oc edit syndesis

    2. Edit the resource by setting managementUrlFor3scale to the URL for your 3scale user interface. The result looks like this:

      spec:
        components:
          server:
            features:
              managementUrlFor3scale: https://3scale-admin.apps.mycluster.com
    3. Save the resource.
  5. Optional. To confirm that discovery is turned on for the project that you switched to, invoke the following command:

    oc describe dc/syndesis-server

    When discovery is turned on, the output from this command shows that the OPENSHIFT_MANAGEMENT_URL_FOR3SCALE environment variable is set to the URL that you specified in the custom resource.

Results

This change to the syndesis custom resource triggers syndesis-operator, which is responsible for installing Fuse Online, to redeploy syndesis-server. In the OpenShift project that you switched to, the new default behavior is that APIs are exposed for discovery in 3scale.

Do not edit the syndesis-server DeploymentConfig object to set the OPENSHIFT_MANAGEMENT_URL_FOR3SCALE environment variable. This does not work because syndesis-operator reverts your change. The syndesis-operator ensures that Fuse Online is deployed only and always according to the syndesis custom resource.

2.3.2. Configuring Fuse Online to disable 3scale discovery of APIs

If you followed the procedure described in Configuring Fuse Online to enable 3scale discovery of APIs, each API provider integration creator can choose whether that integration’s API is discoverable. At some point, you might want to reconfigure the default behavior, which is that integration APIs are not discoverable in 3scale, For example, you might want to edit and test an API provider integration in Fuse Online. To do this, update the Fuse Online syndesis custom resource so that the line that specifies the managementUrlFor3scale key and value is commented out. This disables discovery by 3scale. Then republish any API provider integrations that were published with discoverable APIs.

Prerequisites

  • Fuse Online is installed on OCP on-site.
  • You have permission to install Fuse Online in the project in which you want to disable discovery.
  • The oc client tool is installed and it is connected to the OCP cluster in which Fuse Online is installed.
  • 3scale discovery was enabled in an OpenShift project as described in Configuring Fuse Online to enable 3scale discovery of APIs.

Procedure

  1. Log in to OpenShift with an account that has permission to install Fuse Online. For example:

    oc login -u developer -p developer

  2. Switch to an OpenShift project in which 3scale discovery was enabled. For example:

    oc project my-fuse-online-project

  3. Edit the syndesis custom resource:

    1. Invoke the following command, which typically opens the resource in an editor:

      oc edit syndesis

    2. Edit the resource by inserting a hash sign (#) at the beginning of the line that specifies the managementUrlFor3scale key and value. This makes the line a comment, which disables discovery. The result should look like this:

      spec:
        components:
          server:
            features:
            #  managementUrlFor3scale: https://3scale-admin.apps.mycluster.com
    3. Save the resource.

      This updates the syndesis custom resource. The update removes the OPENSHIFT_MANAGEMENT_URL_FOR3SCALE environment variable. This change to the syndesis custom resource triggers syndesis-operator, which is responsible for installing Fuse Online, to redeploy syndesis-server. The new default behavior is that APIs are no longer exposed for discovery in 3scale.

    Do not edit the syndesis-server DeploymentConfig object to remove the setting of the OPENSHIFT_MANAGEMENT_URL_FOR3SCALE environment variable. This does not work because syndesis-operator reverts your change. The syndesis-operator ensures that Fuse Online is deployed only and always according to the syndesis custom resource.

  4. Republish any API provider integration that had discovery enabled and that was created in the project in which you just disabled discovery.

    In other words, you do not need to republish an API provider integration if you disabled discovery of that integration’s API while discovery was enabled for the project in which the API provider integration was created.

Results

APIs for API provider integrations that were created in the relevant OpenShift project are no longer discoverable in 3scale.

When Fuse Online publishes (or republishes) an API provider integration that is in the relevant project, Fuse Online provides an external URL for invoking the API provider integration operations.

2.4. Configuring Fuse Online pods

You can configure the placement of Fuse Online infrastructure component and integration pods onto nodes within an OpenShift cluster by setting node affinity and tolerations options in the Fuse Online custom resource. The nodeAffinity option allows you to specify an affinity for Fuse Online pods towards a group of nodes to be placed on. The tolerations option allows you to control which nodes the Fuse Online pods run on and to prevent other workloads from using those nodes.

You set these options by editing the Fuse Online custom resource before or after installing Fuse Online.

You specify configure node affinity or tolerations settings for infrastructure component deployments separately from integration deployments:

  • infraScheduling - Specify the infraScheduling option to configure node affinity and tolerations settings for these Fuse Online infrastructure deployments:

    • syndesis-db
    • syndesis-meta
    • syndesis-prometheus
    • syndesis-ui

      Note: The syndesis-operator deployment is not affected by a change in node affinity or tolerations because it is the Fuse Online management component.

  • integrationScheduling - Specify the integrationScheduling option to configure node affinity and tolerations settings for all Fuse Online integration deployments.

    Note: If you want to know whether a Fuse Online deployment is an integration deployment, check the deployment name. You can use the oc get pods command to view a list of running deployments. If a deployment name includes a -i prefix, it is an integration deployment, for example, i-my-integration.

The following procedure describes how to edit the custom resource with the oc patch command. Alternatively, you can edit the custom resource as described in these topics:

Prerequisites

  • Fuse Online is installed on OCP on-site.
  • The oc client tool is installed and it is connected to the OCP cluster in which Fuse Online is installed.

Procedure

  1. Use the oc patch command with the following syntax to configure tolerations settings. Specify infraScheduling for Fuse Online infrastructure component deployments or integrationScheduling for Fuse Online integration deployments:

    oc patch syndesis/app --type=merge -p '{"spec":{"infraScheduling"|"infraScheduling":{"tolerations":[{"key":"_value1_","operator":"_value2_","effect":"_value3_"},{"key":"_value4_","operator":"_value5_","effect":"_value6_"}]}}}'

    For example, the following command adds tolerations for Fuse Online infrastructure components:

    oc patch syndesis/app --type=merge -p '{"spec":{"infraScheduling":{"tolerations":[{"key":"tol_1","operator":"Equal","effect":"NoSchedule"},{"key":"tol_2","operator":"Equal","value":"value2","effect":"NoSchedule"}]}}}'
  2. Use the oc patch command with the following syntax to configure node affinity settings. Specify infraScheduling for Fuse Online infrastructure component deployments or integrationScheduling for Fuse Online integration deployments:

     oc patch syndesis/app --type=merge  -p '{"spec":{"infraScheduling"|"infraScheduling":{"affinity":{"nodeAffinity":{"preferredDuringSchedulingIgnoredDuringExecution":[{"weight":_value1_,"preference":{"matchExpressions":[{"key":"_value1_","operator":"_value2_","values":["_value3_","_value4_"]}]}}]}}}'

    For example, the following command sets nodeAffinity to both Fuse Online infrastructure components and integrations:

     oc patch syndesis/app --type=merge  -p '{"spec":{"infraScheduling":{"affinity":{"nodeAffinity":{"preferredDuringSchedulingIgnoredDuringExecution":[{"weight":11,"preference":{"matchExpressions":[{"key":"_affinity","operator":"In","values":["foo","bar"]}]}}]}}},"integrationScheduling":{"affinity":{"nodeAffinity":{"preferredDuringSchedulingIgnoredDuringExecution":[{"weight":22,"preference":{"matchExpressions":[{"key":"my_affinity2","operator":"In","values":["foo","bar"]}]}}]}}}}}'
  3. To remove a configuration setting, use the remove option in the oc patch command, as demonstrated in the following example commands:

    • The following example command removes the preferredDuringSchedulingIgnoredDuringExecution setting from a nodeAffinity for Fuse Online integrations:

      oc patch syndesis/app --type=json -p '[{"op": "remove", "path": "/spec/integrationScheduling/affinity/nodeAffinity/preferredDuringSchedulingIgnoredDuringExecution" }]'
    • The following example removes the tolerations from Fuse Online infrastructure components:

      oc patch syndesis/app --type=json -p '[{"op": "remove", "path": "/spec/infraScheduling/tolerations" }]'

Additional resources

For information about tolerations and node affinity, see the Understanding node affinity and the Controlling pod placement using node taints sections of the OpenShift documentation.

2.5. Configuring the HTTP proxy

Many services use a HTTP proxy to filter and secure communications with other services or components. To configure the HTTP proxy on Fuse Online components and integrations, edit the Fuse Online custom resource before or after installing Fuse Online.

Prerequisite

  • You know the host and port values for the HTTP proxy.

Procedure

  1. Open the custom resource in an editor:

    If you have already installed Fuse Online, open the custom resource by following the steps in “General procedure for changing Fuse Online configuration.

    If you have not yet installed Fuse Online, open the custom resource by following the steps in these topics, depending on your OCP version.

    For OCP 4.x: Adding a Fuse Online instance to an OpenShift 4.x project

  2. For the syndesis-server and syndesis-meta components, set the Java Options (javaOptions) parameter and specify values for the HTTP proxy host and port. Use the same HTTP proxy values for both syndesis-server and syndesis-meta.

    For example:

    spec:
      components:
        server:
          javaOptions:
    -Dhttp.proxyHost=10.0.0.100 -Dhttp.proxyPort=8800
    
        meta:
          javaOptions:
    -Dhttp.proxyHost=10.0.0.100 -Dhttp.proxyPort=8800
  3. For Fuse Online integrations, set the Maven Arguments (additionalArguments) parameter. For example:

    spec:
      components:
        server:
          features:
            maven:
              additionalArguments: "-Dhttp.proxy=10.0.0.100 -Dhttp.proxyPort=8800"
  4. Save the custom resource.

    If Fuse Online is already installed, the syndesis-server pod is redeployed in response to the javaOptions update in Step 2.

  5. Republish any running integrations that use the HTTP proxy.

    1. In Fuse Online, select the integration that you want to update.
    2. Select Edit.
    3. Select Publish.

Fuse Online uses the HTTP proxy settings when it rebuilds the integration.

2.6. Adding sample data to a Fuse Online environment running on OCP

To help new users learn how to create integrations with Fuse Online, you can add sample data to your Fuse Online environment.

  • The ToDo app
  • The sample PostgresDB database and PostgresDB connection
  • The AMQ Broker

The Salesforce to Database, AMQ to REST API, and API Provider quickstart sample integrations require this sample data.

By default, the AMQ Broker, the sample PostgresDB database and connection, and the ToDo app are disabled (not installed).

To configure Fuse Online to include the sample data before you install Fuse Online, see Descriptions of custom resource attributes that configure Fuse Online.

Prerequisites

  • Fuse Online is installed and running on OCP on-site.
  • The oc client tool is installed and it is connected to the OCP cluster in which Fuse Online is installed.
  • You have permission to edit the Fuse Online custom resource.

Procedure

  1. Log in to OpenShift with an account that has permission to edit the Fuse Online custom resource. For example:

    oc login -u developer -p developer

  2. Switch to the project in which Fuse Online is running. For example:

    oc project my-fuse-online-project

  3. Edit the syndesis custom resource:

    1. Invoke the following command, which typically opens the resource in an editor:

      oc edit syndesis

    2. Edit the custom resource by changing the addons:todo:enabled field to true:

      spec:
        addons:
          todo:
            enabled: true
    3. Save the resource.

      Saving this change to the syndesis custom resource triggers the syndesis-operator to create a new todo pod and triggers the redeployment of the syndesis-server and syndesis-db pods.

Chapter 3. Managing Fuse Online on OCP

After you install Fuse Online on OpenShift Container Platform (OCP) on-site, you can use Prometheus to monitor integration activity, and you can set up periodic Fuse Online backups, which you can use to restore Fuse Online environments. As needed, you can upgrade Fuse Online, uninstall Fuse Online, or delete an OCP project that contains Fuse Online.

See the following topics for details:

3.1. Auditing Fuse Online components

Important

Fuse Online auditing is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production.These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.For more information about the support scope of Red Hat Technology Preview features, see https://access.redhat.com/support/offerings/techpreview/

Fuse Online supports basic auditing for changes made by any user to the following Fuse Online components: * Connections - The Name and any other fields shown on the connector’s Details page in the Fuse Online web console. * Connectors - The Name field. * Integrations - The Name field.

When a developer makes an update to one of these component fields (for example, changes the name of an integration), Fuse Online sends an AUDIT message to standard output that includes information such as ID, user, timestamp, component (connection, connector, or integration), and the type of change (create, modify, or delete). Note that the field values in an audit message are truncated to 30 characters.

By default, Fuse Online auditing is disabled. You can enable it by editing the Fuse Online custom resource. To enable auditing before you install Fuse Online, see Descriptions of custom resource attributes that configure Fuse Online.

Prerequisites

  • The oc client tool is installed and it is connected to the OCP cluster in which Fuse Online is installed.
  • You have permission to edit the Fuse Online custom resource.

Procedure

  1. Log in to OpenShift with an account that gives you permission to edit the Fuse Online custom resource. For example:

    oc login -u admin -p admin-password

  2. Switch to the project that is running the Fuse Online environment. For example:

    oc project my-fuse-online-project

  3. Edit the syndesis custom resource:

    1. Invoke the following command, which typically opens the resource in an editor:

      oc edit syndesis

    2. Ensure that the following lines are in the resource. Edit as needed:

      components:
        server:
          features:
            auditing: true
  4. Save the resource.

    When you enable the auditing feature in the syndesis custom resource, the running syndesis-server configuration reloads and Fuse Online starts logging relevant changes to Fuse Online components.

  5. To view the Fuse Online audit log messages, type the following command:

oc logs -l syndesis.io/component=syndesis-server

3.2. Monitoring Fuse Online integrations and infrastructure components with Prometheus

You can use Prometheus to monitor Fuse Online infrastructure components and Fuse Online integrations. You can also use Grafana dashboards to visualize the metrics gathered by Prometheus.

Important

Red Hat support for Prometheus is limited to the setup and configuration recommendations provided in Red Hat product documentation.

Grafana is a community-supported feature. Deploying Grafana to monitor Red Hat Fuse products is not supported with Red Hat production service level agreements (SLAs).

In addition to monitoring Fuse Online integrations, you can use Prometheus to monitor the metrics exposed by the following Fuse Online infrastructure components:

Syndesis Server
The syndesis-server component has been instrumented with Micrometer and exposes all of the JVM Micrometer metrics automatically by default. Additionally, syndesis-server exposes metrics about the REST API endpoints, such as request rate, error rate, and latency.
Syndesis Meta
The syndesis-meta component has been instrumented with Micrometer and exposes all of the JVM Micrometer metrics automatically by default. It also exposes metrics about its REST API endpoints.
Syndesis DB
Metrics for the Fuse Online Postgres database are exported using a third-party Prometheus exporter.
Integrations
The integration metrics are visible after an integration has been created and are exported by using the official JMX exporter, which exposes several JVM metrics by default. Additionally, integration metrics expose metrics that are specific to Apache Camel, such as message rate and error rate.

Prerequisites

  • Fuse Online is installed and running on OCP 4.9 (or later) on-site.
  • The oc client tool is installed and it is connected to the OCP cluster in which Fuse Online is installed.
  • You have admin access to the OCP cluster.
  • Your Fuse Online installation is configured with the ops addon enabled. If required, you can enable it with this command:

    oc patch syndesis/app --type=merge -p '{"spec": {"addons": {"ops": {"enabled": true}}}}'

Procedure

  1. If there is an existing openshift-monitoring configuration, skip to Step 2.

    Otherwise, create an openshift-monitoring configuration, that sets the user workload monitoring option to true and then skip to Step 3:

    oc apply -f - <<EOF
    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: cluster-monitoring-config
      namespace: openshift-monitoring
    data:
      config.yaml: |
       enableUserWorkload: true
    EOF
  2. If there is an existing openshift-monitoring configuration:

    1. Check the existing openshift-monitoring configuration to determine whether the user workload monitoring option is set to true:

      oc get -n openshift-monitoring cm/cluster-monitoring-config -ojsonpath='{.data.config\.yaml}'

      If the result is enableUserWorkload: true, the user workload monitoring option is set to true. Skip to Step 3.

      If the result shows any other configurations, continue to the next step to enable the monitoring of user workloads by editing the ConfigMap.

    2. Open the ConfigMap file in an editor, for example:

      oc -n openshift-monitoring edit cm/cluster-monitoring-config
    3. Set enableUserWorkload to true. For example:

      apiVersion: v1
      kind: ConfigMap
      metadata:
        name: cluster-monitoring-config
        namespace: openshift-monitoring
      data:
        config.yaml: |
         enableUserWorkload: true
    4. Save the ConfigMap file.
  3. Use the following command to watch the status of the pods in the openshift-user-workload-monitoring namespace:

    oc -n openshift-user-workload-monitoring get pods -w

    Wait until the status of the pods is Running, for example:

    prometheus-operator-5d989f48fd-2qbzd   2/2     Running
    prometheus-user-workload-0             5/5     Running   prometheus-user-workload-1             5/5     Running
    thanos-ruler-user-workload-0           3/3     Running
    thanos-ruler-user-workload-1           3/3     Running
  4. Verify that the Fuse Online alert rules are enabled in Prometheus:

    1. Access the internal prometheus instance

      oc port-forward -n openshift-user-workload-monitoring pod/prometheus-user-workload-0 9090
    2. Open your browser to localhost:9090
    3. Select Status> Targets. You should see three syndesis endpoints.
    4. Press CTRL-C to terminate the port-forward process.
  5. From the OperatorHub, install the Grafana Operator version 4 to a namespace of your choice, for example, to the grafana-middleware namespace. Use the update channel v4
  6. Add a cluster role and a cluster role binding to allow the grafana-operator to list nodes and namespaces:

    1. Download the cluster role YAML file from the grafana-operator website:

      curl https://raw.githubusercontent.com/grafana-operator/grafana-operator/v4/deploy/cluster_roles/cluster_role_grafana_operator.yaml > tmp_role.yaml
    2. Add cluster permission for the grafana-operator to read other namespaces and nodes:

      cat <<EOF >> tmp_role.yaml
        - apiGroups:
            - ""
          resources:
            - namespaces
            - nodes
          verbs:
            - get
            - list
            - watch
      EOF
      oc apply -f tmp_role.yaml
      oc apply -f - <<EOF
      apiVersion: rbac.authorization.k8s.io/v1
      kind: ClusterRoleBinding
      metadata:
        name: grafana-operator
      roleRef:
        name: grafana-operator
        kind: ClusterRole
        apiGroup: ""
      subjects:
        - kind: ServiceAccount
          name: grafana-operator-controller-manager
          namespace: grafana-middleware
      EOF
  7. Enable the grafana-operator to read Grafana dashboards from other namespaces by using the DASHBOARD_NAMESPACES_ALL environment variable to limit the namespaces:

    oc -n grafana-middleware patch subs/grafana-operator --type=merge -p '{"spec":{"config":{"env":[{"name":"DASHBOARD_NAMESPACES_ALL","value":"true"}]}}}'
  8. Check that the grafana pods are recreated:

    oc -n grafana-middleware get pods -w
  9. Optionally, view the grafana-operator logs:

    oc -n grafana-middleware logs -f `oc -n grafana-middleware get pods -oname|grep grafana-operator-controller-manager` -c manager
  10. Add a Grafana custom resource to start a Grafana server pod, for example:

    oc apply -f - <<EOF
    apiVersion: grafana.integreatly.org/v1beta1
    kind: Grafana
    metadata:
      name: grafana-middleware
      namespace: grafana-middleware
    spec:
      config:
        auth:
          disable_signout_menu: true
        auth.anonymous:
          enabled: true
        log:
          level: warn
          mode: console
        security:
          admin_password: secret
          admin_user: root
      dashboardLabelSelector:
      - matchExpressions:
        - key: app
          operator: In
          values:
          - grafana
          - syndesis
      ingress:
        enabled: true
    EOF
  11. Allow the grafana-operator to read monitoring information:

    oc -n grafana-middleware adm policy add-cluster-role-to-user cluster-monitoring-view -z grafana-serviceaccount
  12. Add a GrafanaDatasource to query thanos-querier:

    oc apply -f - <<EOF
    apiVersion: grafana.integreatly.org/v1beta1
    kind: GrafanaDataSource
    metadata:
      name: prometheus-grafanadatasource
      namespace: grafana-middleware
    spec:
      datasources:
        - access: proxy
          editable: true
          isDefault: true
          jsonData:
            httpHeaderName1: 'Authorization'
            timeInterval: 5s
            tlsSkipVerify: true
          name: Prometheus
          secureJsonData:
            httpHeaderValue1: "Bearer $(oc get secret $(oc get secret | grep grafana-serviceaccount-token | awk '{print$1}') -o=jsonpath="{.data.token}" | base64 -d)"
          type: prometheus
          url: "https://$(oc get route thanos-querier -n openshift-monitoring -ojsonpath='{.spec.host}')"
      name: prometheus-grafanadatasource.yaml
    EOF
  13. View the grafana server log:

    oc logs -f `oc get pods -l app=grafana -oname`
  14. To access the grafana URL and view the Fuse Online dashboards:

    echo "https://"$(oc -n grafana-middleware get route/grafana-route -ojsonpath='{.spec.host}')

    In the left panel of the Grafana console, click the search button. A folder (OCP namespace name) containing the dashboards for each Syndesis instance is displayed.

    • For Fuse Online integrations, select Integration - Camel. This dashboard displays the standard metrics exposed by Apache Camel integration applications.
    • For Fuse Online infrastructure components, select one of the following infrastructure dashboards:

      Infrastructure - DB
      Displays metrics related to the Fuse Online Postgres instance.
      Infrastructure - JVM
      Displays metrics about the running JVM for the syndesis-meta or syndesis-server applications. Chose the application that you want to monitor from the Application drop down list at the top of the dashboard.
      Infrastructure - REST APIs
      Displays metrics relating to the Fuse Online infrastructure API endpoints, such as request throughput and latency. Choose the application that you want to monitor from the Application drop down list at the top of the dashboard.

Additional resources

For information about getting started with Prometheus, go to: https://prometheus.io/docs/prometheus/latest/getting_started/

3.3. Fuse Online Metering labels

You can use the OpenShift Metering operator to analyze your installed Fuse Online operator and components to determine whether you are in compliance with your Red Hat subscription. For more information on Metering, see the OpenShift documentation.

The following table lists the metering labels for Fuse Online infrastructure components and integrations.

Table 3.1. Metering Labels for Fuse Online

LabelPossible values

com.company

Red_Hat

rht.prod_name

Red_Hat_Integration

rht.prod_ver

7.8

rht.comp

Fuse

rht.comp_ver

7.8

rht.subcomp

syndesis-db

syndesis-server

syndesis-meta

syndesis-ui

syndesis-prometheus

syndesis-operator

i-<integration name>

rht.subcomp_t

infrastructure (when rht.subcomp = syndesis-*)

application (when rht.subcomp = i-*)

Examples

  • Infrastructure example (where the infrastructure component is syndesis-db)

    com.company: Red_Hat
    rht.prod_name: Red_Hat_Integration
    rht.prod_ver: 7.8
    rht.comp: Fuse
    rht.comp_ver: 7.8
    rht.subcomp: syndesis-db
    rht.subcomp_t: infrastructure
  • Application example (where the integration deployment name is mytestapp)

    com.company: Red_Hat
    rht.prod_name: Red_Hat_Integration
    rht.prod_ver: 7.8
    rht.comp: Fuse
    rht.comp_ver: 7.8
    rht.subcomp: i-mytestapp
    rht.subcomp_t: application

3.4. Backing up a Fuse Online environment

You can configure Fuse Online to periodically back up:

  • The internal PostgreSQL database in which Fuse Online stores connections and integrations.
  • OpenShift resources that syndesis-operator creates and that are needed to run Fuse Online. This includes, but is not limited to, configuration maps, deployment configurations, and service accounts.

You can configure backups for a Fuse Online environment before you install Fuse Online or you can change the configuration of a Fuse Online environment to enable backups.

When Fuse Online is configured to perform backups, Fuse Online zips data into one file and uploads that file to an Amazon S3 bucket that you specify. You can apply a backup to a new Fuse Online environment (no connections or integrations defined) to restore the Fuse Online environment that was backed up.

Prerequisites

  • OCP is running on-site.
  • The oc client tool is installed and connected to the OCP cluster in which Fuse Online is or will be running.
  • A user with cluster administration permissions gave you permission to install Fuse Online in any project that you have permission to access in the cluster.
  • You have an AWS access key and an AWS secret key. For details about obtaining these credentials, see the AWS documentation for Managing Access Keys for IAM Users.
  • You know the AWS region where the S3 bucket that you want to upload to resides.
  • You know the name of the S3 bucket that you want to upload backups to.

Procedure

  1. Log in to OpenShift with an account that has permission to install Fuse Online. For example:

    oc login -u developer -p developer

  2. Switch to the OpenShift project that is or will be running the Fuse Online environment for which you want to configure backups. For example:

    oc project my-fuse-online-project

  3. Create an OpenShift secret. In the command line:

    • Specify syndesis-backup-s3 as shown in the following command format.
    • Replace the AWS variables with your AWS access key, AWS secret key, AWS region in which the bucket resides, and the name of the bucket.

      Use the following command format to create the secret:

      oc create secret generic syndesis-backup-s3 \
      --from-literal=secret-key-id="my-aws-access-key" \
      --from-literal=secret-access-key="my-aws-secret-key" \
      --from-literal=region="aws-region" \
      --from-literal=bucket-name="aws-bucket-name"

      This secret must be present when the backup job is running.

  4. If Fuse Online is not yet installed, you must edit the default-cr.yml file to enable backups. See Editing the syndesis custom resource before installing Fuse Online. After Fuse Online is installed, there will be backup jobs according to the schedule that you specified in the custom resource.

    If Fuse Online is running, you must edit the syndesis custom resource:

    1. Invoke the following command, which opens the syndesis custom resource in an editor:

      oc edit syndesis

    2. Add the following under spec::

      backup:
        schedule: my-backup-interval

      Replace my-backup-interval with the desired duration between backups. To determine how to specify the interval between backups, consult the following resources:

      • cron pre-defined schedules
      • cron intervals

        Do not specify the @ sign in front of the interval. For example, to configure daily backups, the custom resource would contain something like this:

        apiVersion: syndesis.io/v1beta1
        kind: Syndesis
        metadata:
          name: app
        spec:
          backup:
            schedule: daily
  5. Save the file.

    This adds a backup job to syndesis-operator.

Result

If Fuse Online was already running, there is now a Fuse Online backup job according to the schedule that you defined.

Next steps

If Fuse Online needs to be installed, edit the default-cr.yml file to enable any other desired features or set any other parameters. When the default-cr.yml file has all the settings that you want, install Fuse Online in the project that you specified when you created the OpenShift secret.

3.5. Restoring a Fuse Online environment

In a new Fuse Online environment, in which you have not yet created any connections or integrations, you can restore a backup of a Fuse Online environment. After you restore a Fuse Online environment, you must edit the restored connections to update their passwords. You should then be able to publish the restored integrations.

Prerequisites

  • OCP is running on-site.
  • The oc client tool is installed and connected to the OCP cluster in which you want to restore a Fuse Online environment.
  • A user with cluster administration permissions gave you permission to install Fuse Online in any project that you have permission to access in the cluster.
  • There is a Fuse Online environment that was configured to periodically back up data and upload the data to Amazon S3.
  • The Fuse Online release number, for example, 7.6, is the same for the Fuse Online environment that was backed up and the Fuse Online environment in which you want to restore the backup.
  • You have permission to access the AWS bucket that contains the Fuse Online backups.
  • The Fuse Online environment in which you want to restore a backup is a new Fuse Online installation. In other words, there are no connections or integrations that you defined. If you want to restore Fuse Online in a project that has a Fuse Online environment with connections and integrations, then you must uninstall that Fuse Online environment and install a new Fuse Online environment.

Procedure

  1. Download the desired backup file from Amazon S3. Details for doing this are in the AWS documentation for How Do I Download an Object from an S3 Bucket?
  2. Extract the content of the zip file. For example, the following command line unzips the 7.6-2020-03-15-23:30:00.zip file and copies the content into the /tmp/fuse-online-backup folder:

    unzip 7.6-2020-03-15-23:30:00.zip -d /tmp/fuse-online-backup

  3. Decode the Fuse Online database, for example:

    base64 -d /tmp/fuse-online-backup/syndesis-db.dump > /tmp/fuse-online-backup/syndesis-db
  4. Switch to the OpenShift project that is running the new Fuse Online environment. For example, if the new Fuse Online environment is in the my-fuse-online-project, then you would invoke the following command:

    oc project my-fuse-online-project

    The remainder of this procedure assumes that you have switched to the project that contains the new Fuse Online environment.

  5. Obtain the name of the database pod.

    If the restored Fuse Online environment uses the provided, internal, PostgreSQL database, invoke the following command to obtain the name of the database pod:

    oc get pods -l deploymentconfig=syndesis-db -o jsonpath='{.items[*].metadata.name}'

    If the restored Fuse Online environment uses an external database, it is assumed that you know how to obtain the name of the pod for that database.

    In the remaining commands, where you see DATABASE_POD_NAME, insert the name of the database pod for the restored Fuse Online environment.

  6. Scale down the components that are accessing the database in any way.

    1. Scale down syndesis-operator so that other components can be scaled down:

      oc scale deployment syndesis-operator --replicas 0

    2. Scale down the syndesis-server and syndesis-meta components:

      oc scale dc syndesis-server --replicas 0
      oc scale dc syndesis-meta --replicas 0

  7. Send the database backup file to the Fuse Online database pod:

    oc cp /tmp/fuse-online-backup/syndesis-db DATABASE_POD_NAME:/tmp/syndesis-db
  8. Open a remote shell session in the Fuse Online database pod:

    oc rsh DATABASE_POD_NAME

  9. Invoke the following commands to restore the Fuse Online database.

    If a psql command prompts for the database password, and the restored Fuse Online environment uses the provided, internal PostgreSQL database, you can find the password in the POSTGRESQL_PASSWORD environment variable in the syndesis-db deployment configuration. If the restored Fuse Online environment uses an external database, then it is assumed that you know the password.

    cd /tmp
    psql -c 'DROP database if exists syndesis_restore'
    psql -c 'CREATE database syndesis_restore'
    pg_restore -v -d syndesis_restore /tmp/syndesis-db
    psql -c "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = 'syndesis'"
    psql -c 'DROP database if exists syndesis'
    psql -c 'ALTER database syndesis_restore rename to syndesis'

    Fuse Online should now be restored. You can end the RSH session:

    exit

  10. Scale up the Fuse Online components:

    oc scale deployment syndesis-operator --replicas 1

    Scaling syndesis-operator to 1 should bring up the other pods that were scaled down. However, if that does not happen, you can scale them up manually:

    oc scale dc syndesis-server --replicas 1
    oc scale dc syndesis-meta --replicas 1

  11. The server tries to start each restored integration but you need to update connections first. Consequently, ensure that the restored integrations are not running:

    1. Obtain the Fuse Online console route:

      echo "https://$(oc get route/syndesis -o jsonpath='{.spec.host}' )"
    2. Log in into the Fuse Online console with an OpenShift user account that has permission to install Fuse Online.
    3. Display the list of integrations and ensure that all integrations are stopped. If an integration is running, stop it.
  12. For each connection that has a password, you need to update the connection to have the correct password for this Fuse Online environment. The following steps show how to do this for the provided PostgresDB connection.

    1. In the OpenShift console for the project in which this restored Fuse Online environment is running, retrieve the password for the PostgresDB connection. In the syndesis-db deployment, the password is available in the environment variables.
    2. In the Fuse Online console, display the connections.
    3. Edit the PostgresDB connection.
    4. In the connection details for the PostgresDB connection, paste the retrieved password in the Password field.
  13. For each integration, confirm that there are no Configuration Required indicators. If there are, edit the integration to resolve the issues. When all steps in the integration are correct, publish the integration.

    If Fuse Online keeps rolling an integration back to a Stopped state right after the Build step, delete the deployment, ensure that no configuration is required, and try publishing the integration again.

    You can safely ignore the following message if you see it in the log:

    Error performing GET request to https://syndesis-my-fuse-online-project.my-cluster-url/api/v1/metrics/integrations

3.6. Upgrading Fuse Online

From time to time, fresh application images, which incorporate patches and security fixes, are released for Fuse Online. You are notified of these updates through Red Hat’s errata update channel. You can then upgrade your Fuse Online images.

For OCP 4.x, upgrade from Fuse Online 7.10 to 7.11 by following the steps in Upgrading Fuse Online by using the OperatorHub.

You should determine whether upgrading to Fuse Online 7.11 requires you to make changes to your existing integrations. Even if no changes are required, you must republish any running integrations when you upgrade Fuse Online.

3.6.1. Upgrading Fuse Online by using the OperatorHub (OCP 4.x)

Use the OpenShift OperatorHub to upgrade from Fuse Online 7.10 to 7.11.

Note
  • Fuse Online 7.11 requires OpenShift Container Platform (OCP) 4.6 or later. If you are using OCP 4.5 or earlier, you must upgrade to OCP 4.6 or later, if you want to upgrade to Fuse Online 7.11 .
  • On OCP 4.9, When you upgrade to 7.11, the following warning is displayed during the Fuse Online Operator upgrade process:

    W1219 18:38:58.064578 1 warnings.go:70] extensions/v1beta1 Ingress is deprecated in v1.14+, unavailable in v1.22+; use networking.k8s.io/v1 Ingress

    This warning appears because clients (that Fuse Online uses for the Kubernetes/OpenShift API initialization code) access a deprecated Ingress version. This warning is not an indicator of complete use of deprecated APIs and there is no issue with upgrading to Fuse Online 7.11.

The upgrade process from a Fuse Online 7.10 or an earlier 7.11 version to a newer Fuse Online 7.11 version depends on the Approval Strategy that you selected when you installed Fuse Online:

  • For Automatic updates, when a new version of the Fuse Online operator is available, the OpenShift Operator Lifecycle Manager (OLM) automatically upgrades the running instance of the Fuse Online without human intervention.
  • For Manual updates, when a newer version of an Operator is available, the OLM creates an update request. As a cluster administrator, you must then manually approve that update request to have the Fuse Online operator updated to the new version as described in the Manually approving a pending Operator upgrade section of the OpenShift documentation.

During and after an infrastructure upgrade, existing integrations continue to run with the older versions of Fuse Online libraries and dependencies.

To have existing integrations run with the updated Fuse Online version, you must republish the integrations.

3.6.2. Upgrading Fuse Online integrations

When you upgrade to Fuse Online 7.11, you should determine whether you need to make changes to your existing integrations.

Review the Apache Camel updates described in Camel Migration Considerations.

Even if your integrations do not require changes, you must republish any running integrations because during and after an infrastructure upgrade, existing integrations continue to run with the older versions of Fuse Online libraries and dependencies. To have them run with the updated versions, you must republish them.

Procedure

To republish your integrations, in your Fuse Online environment:

  1. In the Fuse Online left navigation panel, click Integrations.
  2. For each integration:

    1. To the right of the integration entry, click three vertical dots and select Edit.
    2. When Fuse Online displays the integration for editing, in the upper right, click Publish.

Publishing forces a rebuild that uses the latest Fuse Online dependencies.

Note

The Fuse Online user interface shows a warning if any element of an integration has a newer dependency that you need to update.

3.7. Uninstalling Fuse Online from an OCP project

You can uninstall Fuse Online from an OCP project without deleting the project nor anything else in that project. After uninstalling Fuse Online, integrations that are running continue to run but you can no longer edit or republish them.

Prerequisite

  • You have an OCP project in which Fuse Online is installed.
  • You exported any integrations that you might want to use in some other OpenShift project in which Fuse Online is installed. If necessary, see Export integrations.

Procedure

  1. Log in to OpenShift with an account that has permission to install Fuse Online. For example:

    oc login -u developer -p developer

  2. Switch to the OpenShift project that is running the Fuse Online environment that you want to uninstall. For example:

    oc project my-fuse-online-project

  3. Delete Fuse Online infrastructure:

    oc delete syndesis app

  4. Delete syndesis-operator DeploymentConfig and ImageStream resources:

    oc delete deployment/syndesis-operator
    oc delete is/syndesis-operator

3.8. Deleting an OCP project that contains Fuse Online

Deleting an OpenShift project in which Fuse Online is installed deletes everything in the project. This includes all integrations that have been defined as well as all integrations that are running.

Prerequisites

  • You have an OCP project in which Fuse Online is installed.
  • You exported any integrations that you might want to use in some other OpenShift project in which Fuse Online is installed. If necessary, see Exporting integrations.

Procedure

Invoke the oc delete project command. For example, to delete an OpenShift project whose name is fuse-online-project, enter the following command:

oc delete project fuse-online-project

Chapter 4. How to invoke Fuse Online public REST API endpoints

When you are running Fuse Online on OCP, each Fuse Online environment can expose public REST API endpoints. External Continuous Integration/Continuous Delivery (CI/CD) tools can invoke these endpoints to operate on the resources that are in that Fuse Online environment.

In each Fuse Online environment, an OpenShift administrator must expose Fuse Online public REST API endpoints before external tools can invoke those endpoints. The command that invokes an API endpoint specifies the URL for the Fuse Online environment on which the endpoint operates, a secret token, and an authorization token.

See the following topics for details:

4.1. Exposing Fuse Online public REST APIs for use by external tools

When you are running Fuse Online on OCP on-site, you might want to use an external tool to copy Fuse Online integrations from one Fuse Online environment to another Fuse Online environment. An external CI/CD tool might be a Jenkins job, an Ansible playbook, a cron-based shell script, or something else. For example, an Ansible playbook can export an integration from a Fuse Online development environment and import it into a Fuse Online testing environment.

To enable this, you must expose Fuse Online public REST API endpoints for each Fuse Online environment. In other words, you must repeat the procedure here in each OpenShift project in which Fuse Online is installed.

Prerequisites

  • You have an OCP project in which Fuse Online is installed.
  • The oc client tool is installed and it is connected to the OCP cluster in which Fuse Online is installed.
  • You use an external CI/CD tool and you want it to copy marked integrations from one Fuse Online environment to another.
  • Cluster administration privileges are required to execute the syndesis-operator grant command. A user who has administrative privileges for the OpenShift project, but not cluster administration privileges, can execute the other commands.

Procedure

  1. Log in to OpenShift with an account that has cluster administration privileges. For example:

    oc login -u admin -p admin

    While cluster administration privileges are required for only the syndesis-operator grant command, this procedure assumes that a cluster administrator is performing all steps.

  2. Switch to an OpenShift project in which Fuse Online is running. You are exposing the public API in only this project. For example:

    oc project fuse-online-north

  3. Grant roles to the syndesis-public-oauthproxy service account. Your OpenShift project uses this service account to run an OAuth proxy service. Specify a user account that has cluster administration privileges. For example:

    syndesis-operator grant --user developer

    This command creates and assigns a cluster role and cluster role binding to the syndesis-public-oauthproxy service account. The ClusterRoleBinding specifies the name of the OpenShift project in which you are exposing the API, which is fuse-online-north in this example:

    • ClusterRole: syndesis-auth-delegator
    • ClusterRoleBinding: syndesis-fuse-online-north-auth-delegator
  4. Create a client service account and grant it permission to access the Fuse Online public API:

    1. Create an OpenShift service account with a name that you choose. For example, the following command creates the cicd-client service account:

      oc create serviceaccount cicd-client

      Commands that invoke public API endpoints use this account to access the public API. Also, you will need this service account to obtain a secret token, which must be specified in calls to API endpoints. This is described in Obtaining a secret token for calling a REST API endpoint.

    2. Grant the client service account permission to access the Fuse Online public API. If fuse-online-north is the name of the OpenShift project in which Fuse Online is installed, and if cicd-client is the name of the service account that you created for accessing the API service, then you would invoke the following command:

      oc policy add-role-to-user edit system:serviceaccount:fuse-online-north:cicd-client`
  5. Edit the syndesis custom resource:

    1. Invoke the following command, which typically opens the resource in an editor:

      oc edit syndesis

    2. Edit the resource so that it enables the public API and specifies the Fuse Online environment’s public address for invoking endpoints as the setting of routeHostname. (If edits to the default-cr.yml file, which was used to install Fuse Online, enabled the public API and specified the route hostname for endpoints, you will not need to edit the resource.)

      Your cluster setup determines the public address that you need to specify. For details, see the OpenShift documentation for routes. In the following example, the route host name is valid for a minishift cluster.

      spec:
        addons:
          publicApi:
            enabled: true
            routeHostname: public-syndesis.192.168.64.63.nip.io
    3. Save (or close) the resource.

      Saving the syndesis custom resource triggers syndesis-operator, which is responsible for installing Fuse Online, to deploy the public API OAuth proxy service.

      If you did not need to edit the syndesis custom resource, then the public API OAuth proxy service has already been deployed. This is probably because publicApi was enabled and its route specified in the default-cr.yml file that was used to install Fuse Online.

Result

In OpenShift, you can now see:

  • A pod for the syndesis-public-oauthproxy deployment configuration.
  • A syndesis-public-oauthproxy service.
  • A syndesis-public-api route.

In the OpenShift project in which you performed this procedure, external CI/CD tools can use Fuse Online public REST API endpoints to export or import Fuse Online integrations.

Next steps

4.2. Description of base URL for Fuse Online public REST API endpoints

The base URL for Fuse Online public REST API endpoints is something like this:

https://public-syndesis.192.168.64.42.nip.io/api/v1/public

The first part of the base URL is different for each Fuse Online environment. When you create the OpenShift application that runs the Fuse Online public OAuth proxy that enables access to public REST API endpoints, you specify the public address of your Fuse Online environment. This address is the first part of the base URL for calling endpoints that operate in that Fuse Online environment. For example:

https://public-syndesis.192.168.64.42.nip.io

The second part of the base URL is the same for all Fuse Online environments:

/api/v1/public

The Fuse Online public REST API provides endpoints that operate on three resources:

  • /integrations are the integrations that are in the Fuse Online environment that is identified in the base URL.
  • /connections are the connections that are in the Fuse Online environment that is identified in the base URL.
  • /environments is the set of environment labels that are in the Fuse Online environment that is identified in the base URL.

4.3. Obtaining a secret token for calling a public REST API endpoint

A command that calls a Fuse Online public REST API endpoint must specify a secret token. This token is for the service account that you created when you exposed the Fuse Online public REST API in a given Fuse Online environment.

Prerequisites

  • You are running Fuse Online on OCP on-site.
  • You exposed the public REST API that is provided by a Fuse Online environment in which you want to invoke endpoints.

Procedure

  1. Obtain the names of the secret tokens for the service account that you created when you exposed the public REST API for this Fuse Online environment. For example, if cicd-client is the name of the service account, you would invoke the following command:

    oc describe serviceaccount cicd-client

    This displays a list of information about the cicd-client service account including the names of its two tokens, which looks something like this:

    Tokens:      cicd-client-token-gxb25
                 cicd-client-token-gxdnv
  2. Display the content of either one of the tokens. For example:

    oc describe secret cicd-client-token-gxb25

    This displays a list of information, including a Data section that displays token: followed by a long series of random characters. This is one of the service account’s two secret tokens.

  3. Copy the secret token, paste it into a file, and save it.

Result

In a curl command, specification of the secret token looks like this:

-H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9.eyJpc3MiOiJrdWJlcm5ldGVzL3NlcnZpY2VhY2NvdW50Iiwia3ViZXJuZXRlcy5pby9zZXJ2aWNlYWNjb3VudC9uYW1lc3BhY2UiOiJzeW5kZXNpcyIsImt1YmVybmV0ZXMuaW8vc2VydmljZWFjY291bnQvc2VjcmV0Lm5hbWUiOiJzeW5kZXNpcy1jZC1jbGllbnQtdG9rZW4tMnZjNmwiLCJrdWJlcm5ldGVzLmlvL3NlcnZpY2VhY2NvdW50L3NlcnZpY2UtYWNjb3VudC5uYW1lIjoic3luZGVzaXMtY2QtY2xpZW50Iiwia3ViZXJuZXRlcy5pby9zZXJ2aWNlYWNjb3VudC9zZXJ2aWNlLWFjY291bnQudWlkIjoiNjUxMjYxNGMtMmYwMS0xMWU5LTk3OWEtNDI1YWNlMzY3MTcyIiwic3ViIjoic3lzdGVtOnNlcnZpY2VhY2NvdW50OnN5bmRlc2lzOnN5bmRlc2lzLWNkLWNsaWVudCJ9.uKsri0JSKJDbgHoQwAhBJSNuWKwJgjegf2QlrCkhxVssSK1zIMZQaF9P5a4R7ZcWRnrZ_345UTqxYVeRlfHWVH0PqBkD-n7PAS9dcKJIFdS1jUHOmL1FTGgc3YW-bz1SlWT93tvK1EhorZ4_-EBfXhSAP4Uumi5qAg3_QUTMDstq233NSwBKYtFOw3Pp1ys3p3y0hcaiLMimeCH60vR4iWvptqqzc5QDigHiPySZNWxs_5awZlwdoIDvR-nSj690aC-49UKFgyEEdzdFU4bI2W4hOyDyhN9fVaIAZQKeJUrJBU-lnFTHI_NAd2OwzOEBpWZuj31Za5w9fU4kf4UDGA'

Next step

Copy the token from your saved file into a command that calls a public REST API endpoint in the given Fuse Online environment.

4.4. How to find integration IDs

In a command that invokes a Fuse Online public REST API endpoint that operates on only a particular integration, you must specify the ID of the integration that you want the endpoint to operate on. Specify one of the following:

  • The integration’s name

    You must specify it exactly as it appears in the Fuse Online console, for example, timer-to-log. If the integration name has any spaces or special characters, then you must specify HTML escape characters.

  • The internal integration ID

    This ID is in the Fuse Online console URL when you view an integration’s summary. To view an integration’s summary, in the left navigation panel, click Integrations. In the list of integrations, click the entry for the integration whose ID you need.

    With the integration summary visible in the browser, you would see something like this at the end of the URL: /integrations/i-Lauq5ShznJ4LcuWwiwcz. This integration’s ID is i-Lauq5ShznJ4LcuWwiwcz.

4.5. Format for specifying curl commands to invoke Fuse Online public endpoints

A curl command that calls a Fuse Online public REST API endpoint has the following format:

curl [options] \
     -H "Content-Type: <media-type>" \
     -H "SYNDESIS-XSRF-TOKEN: awesome" \
     -H `Authorization: Bearer <token>` \
     <base-url><endpoint> \
     [--request <HTTP-method>] \
     [-d <data>] \
     [-o <filename>]

Table 4.1. curl command options

OptionDescription

[options]

Specify curl options that you choose.

<media-type>

For the export and import endpoints, specify multipart/form-data. For all other endpoints, specify application/json.

<token>

Specify a secret token for the OpenShift service account that you created when you exposed the public REST API.

<base-url>

Specify the base URL for the Fuse Online environment that has the integration, connection, or environment label, that you want the endpoint to operate on.

<endpoint>

Specify the endpoint that you want to call.

[--request <HTTP-method>]

Optionally, specify the HTTP method, for example, --request POST.

[-d <data>]

Optionally, depending on the endpoint that is being called, specify arguments that the endpoint requires. For example, to change an integration’s environment label to test, you would specify -d `test`

[-o <filename>]

Optionally, if you need to specify the name of a file that contains output, specify the -o curl option with the name of a file, for example, -o export.zip.

The following curl command invokes the Fuse Online public API endpoint that marks an integration for one or more environments that you specify:

curl -v -k -L -H "Content-Type: application/json" -H "SYNDESIS-XSRF-TOKEN: awesome" -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9.eyJpc3MiOiJrdWJlcm5ldGVzL3NlcnZpY2VhY2NvdW50Iiwia3ViZXJuZXRlcy5pby9zZXJ2aWNlYWNjb3VudC9uYW1lc3BhY2UiOiJzeW5kZXNpcyIsImt1YmVybmV0ZXMuaW8vc2VydmljZWFjY291bnQvc2VjcmV0Lm5hbWUiOiJzeW5kZXNpcy1jZC1jbGllbnQtdG9rZW4tMnZjNmwiLCJrdWJlcm5ldGVzLmlvL3NlcnZpY2VhY2NvdW50L3NlcnZpY2UtYWNjb3VudC5uYW1lIjoic3luZGVzaXMtY2QtY2xpZW50Iiwia3ViZXJuZXRlcy5pby9zZXJ2aWNlYWNjb3VudC9zZXJ2aWNlLWFjY291bnQudWlkIjoiNjUxMjYxNGMtMmYwMS0xMWU5LTk3OWEtNDI1YWNlMzY3MTcyIiwic3ViIjoic3lzdGVtOnNlcnZpY2VhY2NvdW50OnN5bmRlc2lzOnN5bmRlc2lzLWNkLWNsaWVudCJ9.uKsri0JSKJDbgHoQwAhBJSNuWKwJgjegf2QlrCkhxVssSK1zIMZQaF9P5a4R7ZcWRnrZ_345UTqxYVeRlfHWVH0PqBkD-n7PAS9dcKJIFdS1jUHOmL1FTGgc3YW-bz1SlWT93tvK1EhorZ4_-EBfXhSAP4Uumi5qAg3_QUTMDstq233NSwBKYtFOw3Pp1ys3p3y0hcaiLMimeCH60vR4iWvptqqzc5QDigHiPySZNWxs_5awZlwdoIDvR-nSj690aC-49UKFgyEEdzdFU4bI2W4hOyDyhN9fVaIAZQKeJUrJBU-lnFTHI_NAd2OwzOEBpWZuj31Za5w9fU4kf4UDGA'
https://public-syndesis.192.168.64.42.nip.io/api/v1/public/integrations/timer-to-log/tags -d '["test","staging"]' --request PUT

In the sample curl command:

  • The URL at the end of the command identifies the Fuse Online environment whose endpoint you are invoking.
  • timer-to-log indicates that you are marking the timer-to-log integration for the specified environments.
  • Specification of test and staging marks the timer-to-log integration for those environments.

Chapter 5. Using external tools to export/import Fuse Online integrations for CI/CD

When you are running Fuse Online on OCP on-site, you might have Continuous Integration/Continuous Deployment (CI/CD) pipelines that you want to act on certain integrations. Implementing this requires the completion of these tasks:

  • In the Fuse Online console, mark integrations for CI/CD pipelines.
  • In OpenShift, expose the Fuse Online public API.
  • Use external tools to invoke Fuse Online public API endpoints that export and import integrations.

See the following topics for details:

5.1. About marking integrations for CI/CD

When you are running Fuse Online on OCP on-site, to identify an integration for pipelines, mark the integration for a CI/CD environment that you specify. This applies a time-stamped label to the integration. Backend CI/CD Fuse Online public APIs use the label and its timestamp to filter integrations to find an integration that a pipeline needs to act on.

For example, suppose that in Fuse Online you mark an integration for the test1 environment. You can then invoke the Fuse Online public API export endpoint to export integrations that have the test1 environment label. The endpoint packages test1 integrations into an export file and returns that file. To copy test1 integrations to a Fuse Online test environment, you would invoke the public API import endpoint and provide the file that contains the exported test1 integrations.

Now suppose that you iteratively update and publish an integration that you previously marked for the test1 environment. You now have a new version of the integration and you want to export the updated version to the test1 environment. You must mark the integration again, even though it is already marked for the test1 environment. Marking the integration again updates the timestamp on the test1 environment label. This indicates to external tools that the integration has been updated and it is ready to be exported.

To mark an integration again, that is, to refresh the timestamp on an environment label that is already assigned to an integration, start the procedure for Marking integrations for CI/CD. In the CI/CD dialog, click Save since the checkbox for the desired environment should already be selected.

5.2. Marking an integration for CI/CD

When you are running Fuse Online on OCP on-site, to identify an integration for pipelines, mark the integration for a CI/CD environment that you specify. This applies a label to the integration.

Prerequisite

You have an OCP project in which Fuse Online is installed.

Procedure

  1. In the Fuse Online navigation panel on the left, click Integrations.
  2. In the list of integrations, at the right of the entry for the integration that you want to mark, click More Options to display a popup menu and click Manage CI/CD.
  3. In the dialog that appears, do one or more of the following:

    • If the environment for which you want to mark this integration already appears, select the checkbox to the left of that environment.
    • If the environment for which you want to mark this integration is already selected, leave it selected.
    • If you need to create a label for an environment, then click Manage CI/CD, which displays a dialog for creating new environment labels. Create the label that you need, and then return to this procedure to mark the integration.

    Fuse Online applies selected environment label(s) to the integration. You can apply any number of environment labels to an integration.

  4. Click Save.

Result

Fuse Online labels the integration for release in the selected environment. Backend APIs can filter integrations to find the integrations that have, for example, the test1 label.

Next step

You must expose the Fuse Online public API endpoints before pipelines can act on integrations that are marked for a particular environment. See Exposing Fuse Online public REST APIs for use by external tools.

5.3. Managing environment labels for CI/CD

In the Fuse Online console, you can create, change, or remove CI/CD environment labels. CI/CD environment labels are tags that you can apply to integrations to identify them for CI/CD pipelines.

Prerequisites

  • Fuse Online is running on OCP on-site.
  • External tools use Fuse Online environment labels to identify integrations for CI/CD pipelines.

Procedure

  1. In Fuse Online, in the left navigation panel, click Integrations.
  2. In the upper right, click Manage CI/CD.
  3. On the Manage CI/CD page:

    • To create a CI/CD environment label:

      1. Click Add New.
      2. In the Add Tag Name dialog, in the Tag Name input field, enter a name for a new environment label, for example, test1.
      3. Click Save. On the Manage CI/CD page, there is a new entry for the environment label that you just added.
    • To change a CI/CD environment label:

      1. In the list of CI/CD environment labels, in the entry for the label that you want to change, click Edit.
      2. In the Edit Tag dialog, change the name as needed.
      3. Click Save to see the updated name in the list of environment labels. Fuse Online applies the updated name to every integration that is already marked with the environment label that you changed.
    • To delete a CI/CD environment label:

      1. In the list of CI/CD environment labels, in the entry for the label that you want to delete, click Remove.
      2. In the confirmation dialog, click Yes. Fuse Online deletes the environment label and also removes the deleted environment label from any integrations that have been marked with it.

Next step

Mark integrations with new environment labels. See Marking an integration for CI/CD.

5.4. Invoking the Fuse Online public API export endpoint

Before you can use external tools to copy Fuse Online integrations from one Fuse Online environment to another, the following tasks must be completed:

  • In Fuse Online, an integration that you want to export for a CI/CD pipeline must be marked for a particular environment. See Marking an integration for CI/CD.

    There is an exception to this requirement. When you want to export all integrations from a Fuse Online environment in one export operation, it does not matter whether or not an integration has already been marked for a particular environment.

  • You exposed the Fuse Online public API. See Exposing Fuse Online public API endpoints for external tools.

Endpoint for exporting integrations for a particular environment

To export integrations that have been marked for a particular environment, Fuse Online provides the following GET method endpoint:

/public​/integrations​/{env}​/export.zip

Replace {env} with a CI/CD environment label that you already created. When an integration is marked for a particular environment, Fuse Online maintains a timestamp that indicates when it was marked. The default behavior is that the endpoint exports an integration only if it has not already been exported since it was marked. For example, to export integrations that have been marked for the test1 environment, the endpoint is:

/public/integrations/test1/export.zip

This endpoint exports each integration that has the test1 environment label and that meets one of the following conditions:

  • The integration was marked for the test1 environment since the last time that it was exported.
  • The integration was marked for the test1 environment and it has never been exported.

The endpoint packages the integrations in the export.zip file and returns that file.

If no integration that is marked for the specified environment has been marked since the last time that the integration was exported, then the endpoint returns an HTTP 204 response to indicate that there is nothing to return.

Endpoint for exporting all integrations tagged for the specified environment

You can invoke the export endpoint so that it exports all integrations in a Fuse Online environment that are tagged with an environment label that you specify. The endpoint exports the integration whether or not it was marked for the specified environment since the last time the integration was exported. This makes it easy to duplicate all integrations that have a particular tag in another Fuse Online environment. To do this:

  • You must have already created the environment label. See Marking an integration for CI/CD.
  • Add the ignoreTimestamp=true option to the invocation of the export endpoint.

For example:

/public/integrations/test1/export.zip?ignoreTimestamp=true -o export.zip

Endpoint for exporting all integrations

You can invoke the export endpoint so that it exports all integrations in one Fuse Online environment. This makes it easy to duplicate all integrations in another Fuse Online environment. To do this:

For example:

/public/integrations/{env}/export.zip?all=true

Replace {env} with a CI/CD environment label. The endpoint assigns the specified environment label to each integration that is not already marked for that environment.

When you add the all=true option, you must also explicitly specify that you want the exported integrations to be packaged in the export.zip file. For example:

/public/integrations/test1/export.zip?all=true -o export.zip

This invocation of the endpoint:

  • Marks each integration for the test1 environment.
  • Returns all integrations in the export.zip file.

    If you do not specify the -o export.zip option, then the endpoint returns a file whose name is export.zip?all=true.

Custom headers required by export endpoint

A command that invokes the export endpoint must specify these custom headers exactly as follows:

  • -H "Content-Type: multipart/form-data"
  • -H "SYNDESIS-XSRF-TOKEN: awesome"

    The Fuse Online public API requires this header to authenticate the request.

  • -H 'Authorization: Bearer <token>'

    Replace <token> with the secret token that you copied into a file when you created the OpenShift service account that is used to expose the Fuse Online public API.

Sample curl command that exports integrations

Following is an example of a curl command that invokes a Fuse Online API endpoint that exports integrations:

curl -v -k -L -H "Content-Type: multipart/form-data" -H "SYNDESIS-XSRF-TOKEN: awesome" -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9.eyJpc3MiOiJrdWJlcm5ldGVzL3NlcnZpY2VhY2NvdW50Iiwia3ViZXJuZXRlcy5pby9zZXJ2aWNlYWNjb3VudC9uYW1lc3BhY2UiOiJzeW5kZXNpcyIsImt1YmVybmV0ZXMuaW8vc2VydmljZWFjY291bnQvc2VjcmV0Lm5hbWUiOiJzeW5kZXNpcy1jZC1jbGllbnQtdG9rZW4tMnZjNmwiLCJrdWJlcm5ldGVzLmlvL3NlcnZpY2VhY2NvdW50L3NlcnZpY2UtYWNjb3VudC5uYW1lIjoic3luZGVzaXMtY2QtY2xpZW50Iiwia3ViZXJuZXRlcy5pby9zZXJ2aWNlYWNjb3VudC9zZXJ2aWNlLWFjY291bnQudWlkIjoiNjUxMjYxNGMtMmYwMS0xMWU5LTk3OWEtNDI1YWNlMzY3MTcyIiwic3ViIjoic3lzdGVtOnNlcnZpY2VhY2NvdW50OnN5bmRlc2lzOnN5bmRlc2lzLWNkLWNsaWVudCJ9.uKsri0JSKJDbgHoQwAhBJSNuWKwJgjegf2QlrCkhxVssSK1zIMZQaF9P5a4R7ZcWRnrZ_345UTqxYVeRlfHWVH0PqBkD-n7PAS9dcKJIFdS1jUHOmL1FTGgc3YW-bz1SlWT93tvK1EhorZ4_-EBfXhSAP4Uumi5qAg3_QUTMDstq233NSwBKYtFOw3Pp1ys3p3y0hcaiLMimeCH60vR4iWvptqqzc5QDigHiPySZNWxs_5awZlwdoIDvR-nSj690aC-49UKFgyEEdzdFU4bI2W4hOyDyhN9fVaIAZQKeJUrJBU-lnFTHI_NAd2OwzOEBpWZuj31Za5w9fU4kf4UDGA'
https://public-syndesis.192.168.64.42.nip.io/api/v1/public/integrations/dev1/export.zip

In the command:

  • The URL at the end of the command identifies the Fuse Online environment from which to export integrations.
  • Specification of the dev1 environment label indicates that you want to export integrations that have been marked for the dev1 environment and that have not already been exported since they were marked.

5.5. Invoking the Fuse Online public API import endpoint

You can obtain one or more integrations by invoking a Fuse Online public API export endpoint. To copy exported integrations to another Fuse Online environment, invoke the Fuse Online public API import endpoint.

Endpoint for importing an integration

To import integrations, Fuse Online provides the following POST method endpoint:

​/public​/integrations

In the following example, the endpoint imports the integrations that are in the export.zip file and tags them for the testing environment:

/public/integrations -F data=@export.zip -F environment=testing --request POST

An import endpoint always imports the supplied integrations. That is, even if an integration has not changed since the last time it was imported, the endpoint still imports it.

Custom headers required by import endpoint

A command that invokes the import endpoint must specify these custom headers exactly as follows:

  • -H "Content-Type: multipart/form-data"
  • -H "SYNDESIS-XSRF-TOKEN: awesome"

    The Fuse Online public API requires this header to authenticate the request.

  • -H 'Authorization: Bearer <token>'

    Replace <token> with the secret token that you copied into a file when you created the OpenShift service account that is used to expose the Fuse Online public API.

Sample curl command that imports integrations

Following is an example of a curl command that invokes a Fuse Online API endpoint that imports integrations:

curl -v -k -L -H "Content-Type: multipart/form-data" -H "SYNDESIS-XSRF-TOKEN: awesome" -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9.eyJpc3MiOiJrdWJlcm5ldGVzL3NlcnZpY2VhY2NvdW50Iiwia3ViZXJuZXRlcy5pby9zZXJ2aWNlYWNjb3VudC9uYW1lc3BhY2UiOiJzeW5kZXNpcyIsImt1YmVybmV0ZXMuaW8vc2VydmljZWFjY291bnQvc2VjcmV0Lm5hbWUiOiJzeW5kZXNpcy1jZC1jbGllbnQtdG9rZW4tMnZjNmwiLCJrdWJlcm5ldGVzLmlvL3NlcnZpY2VhY2NvdW50L3NlcnZpY2UtYWNjb3VudC5uYW1lIjoic3luZGVzaXMtY2QtY2xpZW50Iiwia3ViZXJuZXRlcy5pby9zZXJ2aWNlYWNjb3VudC9zZXJ2aWNlLWFjY291bnQudWlkIjoiNjUxMjYxNGMtMmYwMS0xMWU5LTk3OWEtNDI1YWNlMzY3MTcyIiwic3ViIjoic3lzdGVtOnNlcnZpY2VhY2NvdW50OnN5bmRlc2lzOnN5bmRlc2lzLWNkLWNsaWVudCJ9.uKsri0JSKJDbgHoQwAhBJSNuWKwJgjegf2QlrCkhxVssSK1zIMZQaF9P5a4R7ZcWRnrZ_345UTqxYVeRlfHWVH0PqBkD-n7PAS9dcKJIFdS1jUHOmL1FTGgc3YW-bz1SlWT93tvK1EhorZ4_-EBfXhSAP4Uumi5qAg3_QUTMDstq233NSwBKYtFOw3Pp1ys3p3y0hcaiLMimeCH60vR4iWvptqqzc5QDigHiPySZNWxs_5awZlwdoIDvR-nSj690aC-49UKFgyEEdzdFU4bI2W4hOyDyhN9fVaIAZQKeJUrJBU-lnFTHI_NAd2OwzOEBpWZuj31Za5w9fU4kf4UDGA'
https://public-syndesis.192.168.64.45.nip.io/api/v1/public/integrations -F data=@export.zip -F environment=testing --request POST

In this command:

  • The URL at the end of the command identifies the Fuse Online environment to import integrations into.
  • The export.zip file contains the integrations to be imported.
  • Specification of environment=testing causes the endpoint to mark each imported integration for the testing environment.
  • This command produces multipart/form-data.

Chapter 6. Fuse Online public REST API endpoints reference

This section provides reference information for each Fuse Online public REST API endpoint. For additional information, see How to invoke Fuse Online public REST API endpoints.

The OpenAPI document that defines the public REST API endpoints is available in your Fuse Online environment at https://<fuse-online-host>/api/v1/openapi.json. However, this document defines the tags object as having three tags: public-api, extensions, and integration-support. Only the public-api tag is accessible when using the OpenShift public OAuth proxy process for Fuse Online. You should ignore the other two tags.

6.1. Endpoint for obtaining the state of an integration

This endpoint returns the state of the specified integration. The state is Running, Stopped, Pending, or Error.

Method and endpoint

GET

/public/integrations/{id}/state

Table 6.1. Parameters

NameTypeDescription

Required Header Parameters

-H "Content-Type: <media-type>"

application/json

Media type that the endpoint requires.

-H "SYNDESIS-XSRF-TOKEN: awesome"

Custom

Required for authentication.

-H 'Authorization: Bearer <token> '

Custom

Secret token for the OpenShift service account that exposes the Fuse Online public REST API. See Obtaining a secret token.

Path Parameter

{id}

string

Required path parameter. Name or internal ID of the integration whose state you want to obtain. See How to find integration IDs.

Request example

In the following example, the endpoint returns the state of the timer-to-log integration:

/public/integrations/timer-to-log/state

Produces

application/json

Response example

{"currentState":"Unpublished","stateDetails":{"id":"i-Lc0JLrsUFtBJfR_ylfEz:5","integrationId":"i-Lc0JLrsUFtBJfR_ylfEz","deploymentVersion":5,"detailedState":{"value":"BUILDING","currentStep":2,"totalSteps":4},"namespace":"syndesis","podName":"i-timer-to-log-5-build","linkType":"LOGS"}}`

6.2. Endpoint for obtaining a list of an integration’s environment labels

This endpoint returns the environment labels (tags) that have been applied to the specified integration.

Method and endpoint

GET

/public/integrations/{id}/tags

Table 6.2. Parameters

NameTypeDescription

Required Header Parameters

-H "Content-Type: <media-type>"

application/json

Media type that the endpoint requires.

-H "SYNDESIS-XSRF-TOKEN: awesome"

Custom

Required for authentication.

-H 'Authorization: Bearer <token> '

Custom

Secret token for the OpenShift service account that exposes the Fuse Online public REST API. See Obtaining a secret token.

Path Parameter

{id}

string

Required path parameter. Name or internal ID of the integration whose environment labels you want to obtain. How to find integration IDs.

Request example

In the following example, the endpoint returns the environment labels for the timer-to-log integration:

/public/integrations/timer-to-log/tags

Produces

application/json

Response example

{"test":{"name":"test","releaseTag":"i-Lc5WI16UFtBJfR_ylggz","lastTaggedAt":1554887553159,"lastExportedAt":1554887330152,"lastImportedAt":1554888047271},"staging":{"name":"staging","releaseTag":"i-Lc5WI16UFtBJfR_ylgfz","lastTaggedAt":1554887553159}}

6.3. Endpoint for marking an integration and keeping unspecified tags

This endpoint uses the PATCH method to mark the specified integration for the specified environment(s). If the integration is already marked for a specified environment, the endpoint updates the timestamp for that environment label. If the integration was previously marked for an environment that is not specified in a new request, the endpoint leaves that tag in place and does not update its timestamp.

This PATCH endpoint is a convenience method for CI/CD tools because it adds tags without the need to remove any other existing tags. This is in contrast to the PUT endpoint, which marks the integration for specified environments and removes any tags for environments that are not specified in the request.

Method and endpoint

PATCH

/public/integrations/{id}/tags

Table 6.3. Parameters

NameTypeDescription

Required Header Parameters

-H "Content-Type: <media-type>"

application/json

Media type that the endpoint requires.

-H "SYNDESIS-XSRF-TOKEN: awesome"

Custom

Required for authentication.

-H 'Authorization: Bearer <token> '

Custom

Secret token for the OpenShift service account that exposes the Fuse Online public REST API. See Obtaining a secret token.

Path Parameter

{id}

string

Required. Name or internal ID of the integration that you want to mark for the specified environment(s). See How to find integration IDs.

Additional Parameters

--request PATCH

 

Specify the PATCH method.

-d [env{,…​}]

string

Required. Specify one or more, comma-separated, environment labels, that you want to add to the specified integration. You must have already created the environment label; the endpoint cannot create a label. See Marking integrations for CI/CD.

Request example

In the following example, the endpoint marks the timer-to-log integration for the test2 and test3 environments:

public/integrations/timer-to-log/tags --request PATCH -d '["test2","test3"]'

Produces

application/json

Response example

{"test2":{"name":"test2","releaseTag":"i-LcXydouUFtBJfR_ylgrz","lastTaggedAt":1555365010746},"test3":{"name":"test3","releaseTag":"i-LcXydouUFtBJfR_ylgsz","lastTaggedAt":1555365010746},"test":{"name":"test","releaseTag":"i-Lc5WI16UFtBJfR_ylggz","lastTaggedAt":1554887553159,"lastExportedAt":1554887330152,"lastImportedAt":1554888047271},"staging":{"name":"staging","releaseTag":"i-Lc5WI16UFtBJfR_ylgfz","lastTaggedAt":1554887553159}}

6.4. Endpoint for marking an integration and removing unspecified tags

This endpoint uses the PUT method to mark the specified integration for the specified environment(s). If the integration was previously marked for an environment that is not specified in the new request, the endpoint removes that environment label from the integration.

To mark an integration without removing unspecified environment labels, call the PATCH method endpoint instead.

Method and endpoint

PUT

/public/integrations/{id}/tags

Table 6.4. Parameters

NameTypeDescription

Required Header Parameters

-H "Content-Type: <media-type>"

application/json

Media type that the endpoint requires.

-H "SYNDESIS-XSRF-TOKEN: awesome"

Custom

Required for authentication.

-H 'Authorization: Bearer <token> '

Custom

Secret token for the OpenShift service account that exposes the Fuse Online public REST API. See Obtaining a secret token.

Path Parameter

{id}

string

Required. Name or internal ID of the integration that you want to mark. See How to find integration IDs.

Additional Parameters

--request PUT

 

Specify the PUT method.

-d [env{,…​}]

string

Required. Specify one or more, comma-separated, environment labels. The endpoint marks the specified integration for these environments. You must have already created the environment label; the endpoint cannot create a label. See Marking integrations for CI/CD.

Request example

In the following example, the endpoint marks the timer-to-log integration for the test2 and test3 environments. If the integration was previously marked for any other environments, the endpoint removes those tags from the integration.

public/integrations/timer-to-log/tags --request PUT -d '["test2","test3"]'

Produces

application/json

Response example

{"test2":{"name":"test2","releaseTag":"i-LcXyw7GUFtBJfR_ylgtz","lastTaggedAt":1555365085713},"test3":{"name":"test3","releaseTag":"i-LcXyw7GUFtBJfR_ylguz","lastTaggedAt":1555365085713}}

6.5. Endpoint for publishing an integration

This endpoint publishes the specified integration. If the integration is already running, then the endpoint stops the integration and re-publishes it.

Method and endpoint

POST

/public/integrations/{id}/deployments

Table 6.5. Parameters

NameTypeDescription

Required Header Parameter

-H "Content-Type: <media-type>"

application/json

Media type that the endpoint requires.

-H "SYNDESIS-XSRF-TOKEN: awesome"

Custom

Required for authentication.

-H 'Authorization: Bearer <token> '

Custom

Secret token for the OpenShift service account that exposes the Fuse Online public REST API. See Obtaining a secret token.

Path Parameters

{id}

string

Required. Name or internal ID of the integration that you want to publish. See How to find integration IDs.

Request example

In the following example, the endpoint publishes the timer-to-log integration.

/public/integrations/timer-to-log/deployments

Produces

application/json

Response example

In this example, the ellipsis indicates the omission of some of the response.

{"id":"i-Lc0JLrsUFtBJfR_ylfEz:8","version":8,"createdAt":1555365135324,"updatedAt":1555365135324,"userId":"system:serviceaccount:syndesis:syndesis-cd-client","currentState":"Pending","targetState":"Published","integrationId":"i-Lc0JLrsUFtBJfR_ylfEz", . .2c+PC9zdmc+","description":"Trigger events based on an interval or a cron expression","isDerived":false},"stepKind":"endpoint"},{"id":"-Lc0I7wqEVfKCDDHC8Jv","configuredProperties":{"bodyLoggingEnabled":"true","contextLoggingEnabled":"true"},"metadata":{"configured":"true"},"stepKind":"log","name":"Log"}]}],"continuousDeliveryState":{"test2":{"name":"test2","releaseTag":"i-LcXyw7GUFtBJfR_ylgtz","lastTaggedAt":1555365085713},"test3":{"name":"test3","releaseTag":"i-LcXyw7GUFtBJfR_ylguz","lastTaggedAt":1555365085713}}}}

6.6. Endpoint for stopping an integration

This endpoint stops the specified integration.

Method and endpoint

PUT

/public/integrations/{id}/deployments/stop

Table 6.6. Parameters

NameTypeDescription

Required Header Parameters

-H "Content-Type: <media-type>"

application/json

Media type that the endpoint requires.

-H "SYNDESIS-XSRF-TOKEN: awesome"

Custom

Required for authentication.

-H 'Authorization: Bearer <token> '

Custom

Secret token for the OpenShift service account that exposes the Fuse Online public REST API. See Obtaining a secret token.

Path Parameter

{id}

string

Required. Name or internal ID of the integration that you want to stop. See How to find integration IDs.

Request example

In the following example, the endpoint stops the timer-to-log integration.

/public/integrations/timer-to-log/deployments stop

Produces

application/json

Response example

No content with a 204 status code

6.7. Endpoint for exporting integrations

This endpoint exports integrations. The default behavior is that the endpoint exports integrations that are marked for the specified environment and that have never been exported or that have not been exported since the last time that they were marked for that environment. You can specify options when you want to do either of the following:

  • Export all integrations in a Fuse Online environment and tag them with the specified environment label.
  • Export all integrations that are tagged with the specified environment label regardless of whether or not an integration was updated and tagged since the last time it was exported.

See also: Invoking the Fuse Online public API export endpoint.

Method and endpoint

GET

/public/integrations/{env}/export.zip

Table 6.7. Parameters

NameTypeDescription

Required Header Parameters

-H "Content-Type: <media-type>"

multipart/form-data

Media type that the endpoint requires.

-H "SYNDESIS-XSRF-TOKEN: awesome"

Custom

Required for authentication.

-H 'Authorization: Bearer <token> '

Custom

Secret token for the OpenShift service account that exposes the Fuse Online public REST API. See Obtaining a secret token.

Path Parameter

{env}

string

Required. Environment label that you created in the Fuse Online console. The endpoint exports the integrations that are marked for this environment.

Query Parameters

all=true

string

Optional. Specify this option to export all integrations that are in the Fuse Online environment. The endpoint exports the current version of each integration. If an integration is not already marked for the specified environment, then the endpoint adds the specified environment label to the integration. You must have already created the environment label; the endpoint cannot create a label.

ignoreTimestamp=true

string

Export all integrations tagged with the specified environment label. Do this regardless of whether or not an integration was edited and tagged since the last time the integration was exported.

Additional Parameter

-o export.zip

string

Required if you specify the query parameter. Without this option, the exported integrations are in a file named export.zip?all=true.

Request examples

In the first example, the endpoint exports integrations that have been marked for the test1 environment and that have never been exported or that have not been exported since the last time that they were marked for that environment.

/public/integrations/test1/export.zip

In the next example, the endpoint exports all integrations that have been marked for the test1 environment. It does not matter whether or not the integration was updated since the last time it was exported.

/public/integrations/test1/export.zip?ignoreTimestamp=true -o export.zip

In the last example, the endpoint ensures that each integration is marked for the test1 environment and returns all integrations in the export.zip file.

/public/integrations/test1/export.zip?all=true -o export.zip

Produces

application/octet-stream

Response

The export.zip file that contains the exported integration(s). The endpoint returns an HTTP status of 204 if there are no integrations to export.

6.8. Endpoint for importing integrations

This endpoint imports the integrations that are in the provided file. See also: Invoking the Fuse Online public REST API import endpoint.

Method and endpoint

POST

/public/integrations

Table 6.8. Parameters

NameTypeDescription

Required Header Parameters

-H "Content-Type: <media-type>"

multipart/form-data

Media type that the endpoint requires.

-H "SYNDESIS-XSRF-TOKEN: awesome"

Custom

Required for authentication.

-H 'Authorization: Bearer <token> '

Custom

Secret token for the OpenShift service account that exposes the Fuse Online public REST API. See Obtaining a secret token.

Additional Parameters

data=@export.zip

string

Required. This is the file that contains the integrations that you want to import. You must have previously invoked the export endpoint to obtain this file.

environment={env}

string

Required. Environment label that you want to add to each imported integration. You must have already created the environment label; the endpoint cannot create a label.

Request example

In the following example, the endpoint imports the integrations that are in the export.zip file and marks them for the testing environment.

/public/integrations -F data=@export.zip -F environment=testing --request POST

Produces

multipart/form-data

Response example

The response is a list of the imported resources, which includes integrations and connections. In the following example, an ellipsis indicates that part of the response is omitted here.

{"lastImportedAt":1554888047271,"results":[{"id":"i-Lc0JLrsUFtBJfR_ylfEz","version":5,"createdAt":1554800274935,"updatedAt":0,"tags":["timer"],"name":"timer-to-log","flows":[{"id":"-Lc0I5AZEVfKCDDHC8Jv","steps":[{"id":"-Lc0I5jnEVfKCDDHC8Jv","configuredProperties":{"period":"900000"},"metadata":…​"description":"Trigger events based on an interval or a cron expression","isDerived":false},"stepKind":"endpoint"},{"id":"-Lc0I7wqEVfKCDDHC8Jv","configuredProperties":{"bodyLoggingEnabled":"true","contextLoggingEnabled":"true"},"metadata":{"configured":"true"},"stepKind":"log","name":"Log"}]}],"continuousDeliveryState":{"staging":{"name":"staging","releaseTag":"i-Lc5WI16UFtBJfR_ylgfz","lastTaggedAt":1554887553159},"test":{"name":"test","releaseTag":"i-Lc5WI16UFtBJfR_ylggz","lastTaggedAt":1554887553159,"lastExportedAt":1554887330152,"lastImportedAt":1554887859824}}}]}

6.9. Endpoint for removing an environment label from a particular integration

This endpoint removes the specified environment label from the specified integration. The environment label itself continues to exist but it no longer marks the specified integration.

Method and endpoint

DELETE

/public/integrations/{id}/tags/{env}

Table 6.9. Parameters

NameTypeDescription

Required Header Parameters

-H "Content-Type: <media-type>"

application/json

Media type that the endpoint requires.

-H "SYNDESIS-XSRF-TOKEN: awesome"

Custom

Required for authentication.

-H 'Authorization: Bearer <token> '

Custom

Secret token for the OpenShift service account that exposes the Fuse Online public REST API. See Obtaining a secret token.

Path Parameters

{id}

string

Required path parameter. Name or internal ID of the integration that you want to unmark. See How to find integration IDs.

{env}

string

Required path parameter. Environment label that you want to remove from the specified integration.

Additional Parameter

--request DELETE

 

Specify the DELETE method.

Request example

In the following example, the endpoint removes the dev1 environment label from the timer-to-log integration.

/public/integrations/timer-to-log/tags/dev1 --request DELETE

Response example

No content with a 204 status code

6.10. Endpoint for creating an environment label

This endpoint creates an environment label. No integrations are marked with this label until you explicitly mark them in the Fuse Online console or by invoking a public API endpoint.

Method and endpoint

POST

/public/environments/{env}

Table 6.10. Parameters

NameTypeDescription

Required Header Parameters

-H "Content-Type: <media-type>"

application/json

Media type that the endpoint requires.

-H "SYNDESIS-XSRF-TOKEN: awesome"

Custom

Required for authentication.

-H 'Authorization: Bearer <token> '

Custom

Secret token for the OpenShift service account that exposes the Fuse Online public REST API. See Obtaining a secret token.

Path Parameter

{env}

string

Required. Environment label that you want to create.

Produces

Does not produce anything but responds as follows:

ResponseDescription

204 No Content

Success.

400 Bad Request

The environment name you specified already exists.

5xx errors

The server is unable to fulfill the request.

Request example

In the following example, the endpoint creates the dev1 environment label:

/public/environments/dev1 --request POST

The dev1 environment label now exists in the Fuse Online environment in which you invoked this endpoint. There are not yet any integrations that are marked with this label.

Response example

No content with response status code 204

6.11. Endpoint for obtaining a list of environment labels

This endpoint returns a list of environment labels that exist in the Fuse Online environment. You create environment labels in the Fuse Online console. See Managing environment labels for CI/CD.

Method and endpoint

GET

/public/environments[?withUses=true]

Table 6.11. Parameters

NameTypeDescription

Required Header Parameters

-H "Content-Type: <media-type>"

application/json

Media type that the endpoint requires.

-H "SYNDESIS-XSRF-TOKEN: awesome"

Custom

Required for authentication.

-H 'Authorization: Bearer <token> '

Custom

Secret token for the OpenShift service account that exposes the Fuse Online public REST API. See Obtaining a secret token.

Path Parameter

withUses

Boolean

Optional. If the command specifies withUses=true, the endpoint returns environment labels and the number of integrations that are marked with that label. If not specified, or set to false, the endpoint returns only environment labels.

Produces

application/json

Request examples

  • /public/environments

    Response example:
    ["env-label-1", "env-label-2"]

  • /public/environments/?withUses=true

    Response example
    [{"name":"env-label-1","uses":1},
    {"name":"env-label-2","uses":0}]

6.12. Endpoint for changing an environment label

This endpoint changes an environment label. Integrations that were marked for the original environment label are now marked for the new environment label.

Method and endpoint

PUT

/public/environments/{env}

Table 6.12. Parameters

NameTypeDescription

Required Header Parameters

-H "Content-Type: <media-type>"

application/json

Media type that the endpoint requires.

-H "SYNDESIS-XSRF-TOKEN: awesome"

Custom

Required for authentication.

-H 'Authorization: Bearer <token> '

Custom

Secret token for the OpenShift service account that exposes the Fuse Online public REST API. See Obtaining a secret token.

Path Parameter

{env}

string

Required. Environment label that you want to change.

Additional Parameters

-d {env}

string

Required. Specify the new label for the environment. You must have already created the environment label; the endpoint cannot create a label.

--request PUT

 

Specify the PUT method.

Request example

In the following example, the endpoint changes the dev1 environment label to dev2:

/public/environments/dev1 -d ‘dev2’ --request PUT

Integrations that were marked for the dev1 environment no longer have that tag. Those integrations are now marked for the dev2 environment.

Response example

No content with response status code 204

6.13. Endpoint for removing an environment label from all integrations

This endpoint removes the specified environment label from each integration to which it has been applied.

Method and endpoint

DELETE

/public/environments/{env}

Table 6.13. Parameters

NameTypeDescription

Required Header Parameters

-H "Content-Type: <media-type>"

application/json

Media type that the endpoint requires.

-H "SYNDESIS-XSRF-TOKEN: awesome"

Custom

Required for authentication.

-H 'Authorization: Bearer <token> '

Custom

Secret token for the OpenShift service account that exposes the Fuse Online public REST API. See Obtaining a secret token.

Path Parameter

{env}

string

Required. Environment label that you want to remove from integrations that have it.

Additional Parameter

--request DELETE

 

Specify the DELETE method.

Request example

In the following example, the endpoint removes the dev1 tag from any integrations that have it:

/public/environments/dev1 --request DELETE

Response example

No content with response status code 204

6.14. Endpoint for changing a connection’s properties

This endpoint changes the properties of the specified connection. This is often useful after you import an integration that has connections that require configuration. For example, you might need to change the credentials that a connection uses.

Method and endpoint

POST

​/public​/connections​/{id}​/properties

Table 6.14. Parameters

NameTypeDescription

Required Header Parameters

-H "Content-Type: <media-type>"

application/json

Media type that the endpoint requires.

-H "SYNDESIS-XSRF-TOKEN: awesome"

Custom

Required for authentication.

-H 'Authorization: Bearer <token> '

Custom

Secret token for the OpenShift service account that exposes the Fuse Online public REST API. See Obtaining a secret token.

Path Parameter

{id}

string

Required. Replace {id} with the ID of the connection whose properties you want to change. For the connection ID, specify one of the following:

  • The connection’s name, for example: PostgresDB. If the connection name has any spaces or special characters, then you must specify HTML escape characters.
  • The internal connection ID, which is in the Fuse Online console URL when you view a connection’s details. To view a connection’s details, in the left navigation panel, click Connections. Then click the connection whose details you want to view. When the connection details are visible in the browser, you would see something like this at the end of the URL: /connections/i-LaupI8XznJ4LcuWwiwaz. This connection’s ID is i-LaupI8XznJ4LcuWwiwaz.

Request example

The following example changes the properties of the PostgresDB connection. The new value of the user property is myuser, and the new value of the password property is mypassword:

/public/connections/PostgresDB/properties --request POST -d '{ "user": "myuser", "password": "mypassword" }'

Produces

application/json

Sample response

In this example, there is an ellipsis that indicates the omission of a large part of the response.

{"uses":0,"id":"i-LaOziUGpQE45nua4pfCz","name":"TODO app","configuredProperties":{"password":"»ENC:c2cb731046372a275b76beabc92aefa061f79b43fb791fb599d9e85ec0235a7e","basePath":"/api","host":"http://todo-syndesis.my-minishift.syndesis.io/","specification":…​"userId":"admin","lastUpdated":1555365796629,"createdDate":1553066813379,"board":{"id":"i-Lbj4-vqUFtBJfR_ylfCz","metadata":{"connector-id":"i-LaOzcPZpQE45nua4pfBz","connector-version-latest":"1","connector-version-connection":"1"},"messages":[{"level":"WARN","code":"SYNDESIS007"}],"createdAt":1554494263030,"updatedAt":1554494263727,"targetResourceId":"i-LaOziUGpQE45nua4pfCz","notices":0,"warnings":1,"errors":0},"isDerived":false}

Chapter 7. Rebranding the Fuse Online user interface

You can rebrand Fuse Online by replacing the Fuse Online application name, logo, icons, and other user interface details. You do this by mounting customized resources as ConfigMap objects in the syndesis-ui deployment file.

Prerequisites

  • Fuse Online is installed and running on OpenShift Container Platform on-site in a customer-managed environment.
  • The oc client tool is connected to the OCP cluster in which Fuse Online is installed.
  • You have permission to install Fuse Online.

Procedure

  1. Obtain the name of the syndesis-ui pod in which Fuse Online is installed by invoking the following command:

    oc get pods

  2. Fetch customizable logos, icons, fonts, and backgrounds by invoking the following command and replacing SYNDESIS_UI_POD_NAME with the actual name of the pod that is running syndesis-ui:

    oc rsync SYNDESIS_UI_POD_NAME:/opt/app-root/src/static/media ~/

    This puts user interface resources in the the ~/media/ folder.

  3. Edit and save the file that contains the header logo, which is ~/media/syndesis_logo_full_darkbkg.9c467d96.svg.
  4. Upload the modified file to the cluster by creating a ConfigMap object that contains the updated logo file:

    cd ~/
    oc create configmap syndesis-ui-custom-logo --from-file=media/syndesis_logo_full_darkbkg.9c467d96.svg
  5. Modify the syndesis-ui deployment file to mount the syndesis-ui-custom-logo ConfigMap object. Do this by invoking oc edit dc/syndesis-ui or by using the OpenShift web console, selecting Applications > Deployments > syndesis-ui > Actions > Edit YAML.

    1. Under spec.template.containers.volumeMounts, add the following:

      -name: syndesis-ui-custom-logo-volume
       mountPath: /opt/app-root/src/static/media/syndesis_logo_full_darkbkg.9c467d96.svg
       subPath: syndesis_logo_full_darkbkg.9c467d96.svg
    2. Under spec.template.volumes, add the following:

      -name: syndesis-ui-custom-logo-volume
       configMap:
        name: syndesis-ui-custom-logo
    3. Save the syndesis-ui deployment file.
  6. Repeat steps 3 through 5 for each file that is in the `~/media folder and that you want to customize.
  7. Edit and save the file that contains the application title:

    1. Create a directory in which to update the file:

      mkdir ~/syndesis-custom/src

    2. Fetch the application title file by invoking the following command and replacing SYNDESIS_UI_POD_NAME with the actual name of the pod that is running syndesis-ui:

      oc rsync SYNDESIS_UI_POD_NAME:/opt/app-root/src/index.html ~/syndesis-custom/src
    3. Replace the application title. For example:

      sed -i 's/<title>.*<\/title>/<title>NEW_TITLE<\/title>/g' ~/syndesis-custom/src/index.html
  8. Upload the modified application title file to the cluster by creating a ConfigMap object that contains the updated file:

    cd ~/syndesis-custom/src
    oc create configmap syndesis-ui-custom-index --from-file=index.html
  9. Modify the syndesis-ui deployment by mounting the syndesis-ui-custom-index ConfigMap object:

    1. Under spec.template.containers.volumeMounts, add the following:

      -name: syndesis-ui-custom-vindex-olume
       mountPath: /opt/app-root/src/index.html
       subPath: index.html
    2. Under spec.template.volumes, add the following:

      -name: syndesis-ui-custom-index-volume
       configMap:
        name: syndesis-ui-custom-index
    3. Save the syndesis-ui deployment file.

Results

Saving the syndesis-ui deployment file automatically redeploys Fuse Online with a user interface that reflects your changes. Subsequent re-deployments of Fuse Online also reflect your changes.

Legal Notice

Copyright © 2023 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.