Chapter 10. Installing and managing Fuse Online on OpenShift Container Platform

To install Fuse Online on OCP on-site, the main steps are:

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. The administrator also grants permission for installing Fuse Online to the appropriate users. Each user can then install Fuse Online in their projects.

To correctly specify the Fuse Online installation command, decide on the answers to these questions:

To install Fuse Online on OCP on-site, download the installation package, run it, and confirm that Fuse Online is installed.

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 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 for each installation of Fuse Online. For Fuse Online installations on the same cluster, while you can use the same service account to expose the public APIs, the recommendation is to use a different service account for each installation for better security.

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:

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.

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

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:

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>]

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:

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 to follow the procedure for Marking integrations for CI/CD. In the CI/CD dialog, you just need to click Save since the checkbox for the desired environment should already be selected.

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.

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

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

Replace {env} with a CI/CD environment label that you created in the Fuse Online console or by calling a Fuse Online public API endpoint for marking an integration. When an integration is marked for a particular environment, Fuse Online maintains a timestamp that indicates when it was marked. 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 has been marked for the test1 environment since the last time that it was 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.

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

Replace {env} with a CI/CD environment label. It does not matter whether or not you already created this label in the Fuse Online console. 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:

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:

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.

​/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

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.

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.45.nip.io/api/v1/public/integrations -F data=@export.zip -F environment=testing

In this command:

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

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

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

/public/integrations/timer-to-log/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.

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

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.

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

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

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

{"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}}}}

This endpoint stops the specified integration.

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

This 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. See also: Invoking the Fuse Online public REST API export endpoint.

/public/integrations/test1/export.zip

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

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

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

{"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}}}]}

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.

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

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 Marking integrations for CI/CD.

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

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

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

/public/environments/dev1 --request DELETE

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.

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

{"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}

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. It uses the Kubernetes Operator SDK to deploy integrations (for example, automatically creating 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 Camel K Operator is available in Fuse Online to speed up turnaround times when deploying and redeploying integrations on OCP (for example, from 1-2 minutes to a few seconds). This section explains how to install and configure Camel K with Fuse Online from the Syndesis open source project.