Chapter 5. Using external tools to export/import 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
- In the Fuse Online navigation panel on the left, click Integrations.
-
In the list of integrations, at the right of the entry for the integration that you want to mark, click
to display a popup menu and click Manage CI/CD.
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.
- 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
- In Fuse Online, in the left navigation panel, click Integrations.
- In the upper right, click Manage CI/CD.
On the Manage CI/CD page:
To create a CI/CD environment label:
- Click Add New.
- In the Add Tag Name dialog, in the Tag Name input field, enter a name for a new environment label, for example, test1.
- 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:
- In the list of CI/CD environment labels, in the entry for the label that you want to change, click Edit.
- In the Edit Tag dialog, change the name as needed.
- 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:
- In the list of CI/CD environment labels, in the entry for the label that you want to delete, click Remove.
- 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 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.
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:
- You must have already created the environment label. See Marking an integration for CI/CD.
-
Add the
all=true
option to the invocation of the export endpoint.
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 isexport.zip?all=true
.
Custom headers required by export endpoint
A command that invokes the export endpoint must specify these custom headers:
-
-H "Content-Type: multipart/form-data"
-H "SYNDESIS-XSRF-TOKEN: awesome"
You must specify this custom header exactly as it appears above. 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 thedev1
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:
-
-H "Content-Type: multipart/form-data"
-H "SYNDESIS-XSRF-TOKEN: awesome"
You must specify this custom header exactly as it appears above. 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 thetesting
environment. -
This command produces
multipart/form-data
.