Chapter 1. Installing Fuse Online on OCP

Installation of Fuse Online requires a cluster administrator to register the Fuse Online custom resource definition and grant installation permission to the appropriate user(s). The user who installs Fuse Online must determine whether to install a default Fuse Online environment or a customized Fuse Online environment. For a customized Fuse Online environment, editing of the default custom resource file is required.

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

Important

The Fuse Online installation process requires access to registry.redhat.io, which is the Red Hat catalog for container images. Fuse Online does not support or test the use of external container registries, custom registries, or registries in disconnected environments.

The following topics provide details for installing Fuse Online:

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

To install Fuse Online on OCP on-site, a cluster administrator must perform some tasks and then a user who has permission to install Fuse Online in a particular OpenShift project performs some tasks and runs the installation script. The following diagram shows the workflow:

Workflow for installing Fuse Online on OCP

For each OpenShift project in which Fuse Online is to be installed, the cluster administrator must grant permission to a user to install Fuse Online in that particular project.

To install a default Fuse Online environment, the user with permission to install Fuse Online downloads and runs the installation script. No other steps are required.

Additional resource

Fuse Online installation readme file

1.2. Registering a custom resource definition for deploying Fuse Online resources

To enable installation of Fuse Online, a cluster administrator registers a custom resource definition. The administrator needs to do this only once for the OpenShift cluster. Then, for each project in which the administrator wants Fuse Online to be installed, the administrator grants an appropriate user permission to install Fuse Online in that project.

Prerequisites

  • You must have cluster administration permissions.
  • You installed the oc client tool and it is connected to the OCP cluster into which Fuse Online will be installed.
  • On your OCP environment, at least three persistent volumes are available for use by Fuse Online.

Procedure

  1. Download the package that contains the Fuse Online installation script from the following location:

    https://github.com/syndesisio/fuse-online-install/releases/tag/1.9

  2. Unpack the downloaded archive at a convenient location on your file system. The fuse-online-install-1.9 directory contains the script and supporting files for installing Fuse Online.

  3. Log in to OpenShift with an account that has cluster admin permissions. For example:

    oc login -u admin -p adminpwd

  4. Confirm that you are properly connected by running the following command, which lists any custom resource definitions that are already registered in this cluster.

    oc get crd

    You are properly connected if there is no error message.

  5. Register the custom resource definition at the cluster level by switching to the fuse-online-install-1.9 directory and invoking the following command:

    bash install_ocp.sh --setup

  6. Confirm that registration was successful by running the following command again:

    oc get crd

    The output list of registered custom resource definitions should include syndesis.

  7. In each project in which you want Fuse Online to be installed, grant installation permission to a user. For each project:

    1. Change to the project in which you want a user to be able to install Fuse Online. For example:

      oc project fuse-online-project

    2. Grant a user permission to install Fuse Online in that project. For example, the following command grants permission to install Fuse Online to developer user. After running this command, the developer user can install Fuse Online in the current project, which is fuse-online-project in this example:

      bash install_ocp.sh --grant developer

      Repeat these two commands for each OpenShift project in which you want to grant permission for Fuse Online installation. A single user can install Fuse Online in more than one project in the cluster. To enable this, change to another project and specify the same user, for example:

      oc project another-fuse-online-project
      bash install_ocp.sh --grant developer

Result

The syndesis custom resource definition is registered in the cluster.

Next steps

Users with permission to install Fuse Online must decide whether to install a default Fuse Online environment or a customized Fuse Online environment.

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

The Fuse Online download package includes the default-cr.yml file, which specifies the default settings for configurable Fuse Online environment add-on features and parameter settings. Installation of Fuse Online uses the default-cr.yml file to create the syndesis custom resource, which controls the Fuse Online environment’s configuration.

You need to edit the default-cr.yml file before you install Fuse Online only 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.
  • Run the Camel K runtime engine in place of the Spring Boot runtime for Camel integrations. The Camel K runtime is a Technology Preview feature.
  • Enable access to Knative resources. Knative resource access is a Technology Preview feature.
  • 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 default-cr.yml file before 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.4. 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.

The table below provides a brief description of configurable custom resource settings and indicates whether you can change them only before installation. To achieve the Fuse Online configuration that you want, use the information in this table to determine how you need to change the default-cr.yml file before installation or how you want to change the syndesis custom resource after installation. Then follow the appropriate procedure:

Important

Camel K runtime, access to Knative resources, and data virtualization are Technology Preview features 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/.

Feature/SettingWhen you can set thisSpecification

Camel K runtime (Technology Preview)

Additional information about the Camel K runtime follows this table.

Set only before installation

addons:
  camelk:
    enabled: true

Enhanced activity tracking

Additional information about enhanced activity tracking follows this table.

Set only before installation

addons:
  jaeger:
    enabled: 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.

Knative resource access
(Technology Preview)

To enable access to Knative resources, you must also enable the Camel K runtime.

Set only before installation

addons:
  camelk:
    enabled: true
  knative:
    enabled: true

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

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.

Data virtualization
(Technology Preview)
Additional information about the data virtualization feature follows this table.

Set before or after installation

addons:
  dv:
    enabled: true
      resources:
        memory: 1024Mi

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

Maven

Specify external Maven repositories that your Fuse Online environment needs to access.

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.

Memory

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.

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.

Set before or after installation

components:
  database:
    resources:
      memory: 270Mi
  meta:
    resources:
      memory: 300Mi
  server:
    resources:
      memory: 810Mi

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 app
For testing sample integrations.

Set before or after installation

addons:
  todo:
    enabled: true

About add-on features and configuration settings

  • Camel K runtime engine (Technology Preview)

    The Apache Camel K runtime speeds up turnaround times when deploying and redeploying integrations on OCP. For example, performance can improve from 1-2 minutes to a few seconds. When Camel K is installed as the runtime engine, it replaces the Spring Boot runtime for Camel integrations.

    Apache Camel K is a lightweight cloud integration platform based on the Apache Camel framework for Enterprise Integration Patterns. Camel K runs natively on Kubernetes, OpenShift, and Knative, and is specifically designed and optimized for serverless and microservice architectures. Camel K provides automation and performance optimizations when running integrations in the cloud. Camel K uses the Kubernetes Operator SDK to deploy integrations, for example, it automatically creates services and routes on OCP.

    Camel K is a subproject of the Apache Camel open source community. For more details, see https://github.com/apache/camel-k.

    The following limitations apply when the Camel K runtime is installed with Fuse Online:

    • Fuse Online extensions are not supported by the Camel K runtime.
    • Extensions are not displayed in the Fuse Online user interface under Customizations.

  • Data virtualization (Technology Preview)

    Data virtualization lets a Fuse Online developer integrate data from multiple heterogeneous sources to create a virtual database image that is deployable on OpenShift. For details, see the Red Hat Integration data virtualization documentation.

  • Enhanced activity tracking

    If you run the install_ocp.sh script to install Fuse Online, the default behavior is that enhanced activity tracking is enabled in the Fuse Online environment. If you use OperatorHub, then the recommendation is that you enable enhanced activity tracking before you install Fuse Online. The user interface guides you in doing this.

  • 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 Amazon RDS for PostgreSQL.

  • 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.

1.5. Editing the default custom resource file before installing Fuse Online

To install a default Fuse Online environment, you do not need to edit the default custom resource file. See Installing Fuse Online on OCP.

To install a customized Fuse Online environment, you must edit the default-cr.yml file before you install Fuse Online. This file is in the Fuse Online download package. There are some custom resource settings that you can specify only before Fuse Online installation. See When editing the default custom resource is required before installation.

There are other custom resource settings that you can specify before or after Fuse Online installation. See Descriptions of custom resource attributes that configure Fuse Online.

The Fuse Online installation process uses the settings that you specify in the default-cr.yml file to create the syndesis custom resource. The syndesis custom resource settings determine the configuration of the installed Fuse Online environment.

Prerequisites

  • You plan to install and run Fuse Online on OCP on-site.
  • 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. If you did not already download the package that contains the Fuse Online installation scripts:

    1. Download it now from the following location:

      https://github.com/syndesisio/fuse-online-install/releases/tag/1.9

    2. Unpack the downloaded archive at a convenient location on your file system. The fuse-online-install-1.9 directory contains the scripts and supporting files for installing Fuse Online.

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

    oc login -u developer -p developer

  3. Open the fuse-online-install-1.9/default-cr.yml file in an editor.
  4. Edit the default-cr.yml file so that it enables the features and sets the parameters that you want. To determine what you need to specify, see Descriptions of custom resource attributes that configure Fuse Online.
  5. Save the default-cr.yml file.

Result

The default-cr.yml file contains the configuration specifications for a new Fuse Online installation.

Next steps

If you edited the default-cr.yml file to specify an external database then follow the instructions in Creating a secret for installing Fuse Online with an external database before you install Fuse Online. Otherwise, you are ready to follow the instructions in Installing Fuse Online on OCP.

1.6. Creating a secret for 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 an OpenShift secret, syndesis-global-config, before you install Fuse Online.

Prerequisites

  • You edited the default-cr.yml file to specify the use of an external database to persist connection and integration definitions.
  • 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 and save a resource file, for example, my-fuse-onling-secret-cr.yml) that contains the following: 

    apiVersion: v1
kind: Secret
metadata:
  name: syndesis-global-config
  namespace: my-fuse-online-project
  type: Opaque
  data:
    POSTGRESQL_PASSWORD: base64-encoded-value

    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 base64-encoded-value with a base64-encoded value that Fuse Online will use as the password for accessing the external database.

    For information about OpenShift secrets, see Secrets.

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

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

Result

In the 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.

Next step

Follow the instructions in Installing Fuse Online on OCP.

1.7. Running the script that installs Fuse Online on OCP

The Fuse Online installation script installs a Fuse Online environment according to the specifications in the default-cr.yml file, which is in the Fuse Online download package. To install a default environment, no editing of that file is required. To install a customized environment, you must edit the default-cr.yml file before you run the installation script.

Prerequisites

Procedure

  1. If you did not already download the package that contains the Fuse Online installation scripts:

    1. Download it from the following location:

      https://github.com/syndesisio/fuse-online-install/releases/tag/1.9

    2. Unpack the downloaded archive at a convenient location on your file system. The fuse-online-install-1.9 directory contains the scripts and supporting files for installing Fuse Online.

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

    $ oc login -u developer -p developer

  3. Switch to the OpenShift project into which you want to install Fuse Online, for example:

    $ oc project my-fuse-online-project

    Alternatively, when you run the installation script, you can specify, for example, --project my-fuse-online-project.

  4. In the directory in which you downloaded the installation script, invoke the installation script:

    bash install_ocp.sh

    To learn about the installation script options, invoke the $ bash install_ocp.sh --help command.

  5. Confirm that the syndesis custom resource that syndesis-operator used to install Fuse Online contains exactly the content that you want:

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

      oc describe syndesis/app

    2. Check the content of the custom resource.

      If it does not contain all of your updates, then there was probably a syntax error in the custom resource. You must uninstall Fuse Online and try again to define a valid custom resource. See Uninstalling Fuse Online from an OCP project.

  6. Confirm that installation was successful:

    1. Display the OpenShift OAuth proxy log-in page at https://openshift-route.

      If you chose to let the installation script calculate the OpenShift route, then the script displays the calculated route near the end of its execution. Replace openshift-route with the value that the script provided.

      If you edited the default-cr.yml file to specify the routeHostname for Fuse Online, replace openshift-route with the route that you specified.

    2. If you are not already logged in to the OpenShift console, its log-in page appears. Enter your OpenShift user name and password to log in.

    The Fuse Online home page appears either immediately or after you log in to the OpenShift console.

Additional resource

Fuse Online installation readme file