Chapter 6. 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:

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

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

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

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

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