Setting up CI/CD

As they make progress in the development of an IntegrationIntegration - An integration is the place the you write your code to get things done! Written in NodeJS, an integration runs in Fusebit's secure and scalable environment to translate between the needs of your backend application and the remote service or services you're connecting to., teams seek ways to incorporate its code into their existing devops pipeline. One common approach is to store the Integration code in source control, and deploy any changes to Fusebit automatically, once they have gone through code review and testing. Very commonly, GitHub Actions are used to facilitate this process on top of hosted git repositories.

This continuous integration and deployment process (CD/CD) is made possible with the Fusebit CLIFusebit CLI - https://www.npmjs.com/package/@fusebit/cli.

Setting up a Client

When using the Fusebit Management PortalFusebit Management Portal - The Fusebit Management Portal enables you to easily setup and manage all your integrations in one place. Link: https://manage.fusebit.io or CLI to deploy code changes, usually a live human developer - a UserUser - Human (as opposed to machine) consumers of the Fusebit HTTP API in Fusebit terminology - is driving the process. In a CI/CD setup, the deployment will be initiated by a machine process, or what is known as a ClientClient - Machine consumers of the Fusebit HTTP API such as CI/CD infrastructure, or code executing as part of a backend API or other system in Fusebit terms. More details on Users and Clients is available here.

The first step is to create the Client itself. The only input you need to provide to the command is a display name. This can be any value that is meaningful to you.

fuse client add "GitHub Actions"

The output of the client add command should look like the following:

Add Client        │  Adding the client...            

Client Added      │  Client 'clt-7421808fb9e24d16' was successfully added

GitHub Actions    │  Id: clt-7421808fb9e24d16

Granting Access to a Client

The next step is to provide the Client with the proper access. Your User has full permissions on your Account and can therefore Create and grant permissions to a Client.

To grant access to the Client with the CLI fuse client access add command, plugging in the Client and Account IDs as shown.

fuse client access add {client id} '*' --resource /account/{account id}
fuse client access add clt-7421808fb9e24d16 '*' --resource /account/acc-6c9a76edb66f4e8a

The output should look like the following:

Add Access        │  Adding the access to client 'clt-7421808fb9e24d16'...      

Access Added      │  The access was successfully added to client                
                  │  'clt-7421808fb9e24d16'                                     

GitHub Actions    │  Id: clt-7421808fb9e24d16                                   
                  │                                                             
                  │  Identities                                                 
                  │  • iss:                                                     
                  │  1d677b6e.clt-7421808fb9e24d16.api.us-west-1.on.fusebit.io  
                  │    sub: cli-477dee4d                                        
                  │                                                             
                  │  Allow                                                      
                  │  • action:   *                                  
                  │    resource: /account/acc-6c9a76edb66f4e8a

Setting up Access from CI/CD

The Client we just created needs to be associated with a known IssuerIssuer - The basis of trust within the Fusebit platform. For an Access Token to be accepted by the Fusebit HTTP API, it must be issued by a trusted Issuer. The Issuer may be a third-party identity provider like Google or Auth0, or a backend service that integrates with the Fusebit platform that issues its own access tokens. within Fusebit, so when it makes calls into the Fusebit HTTP API from your CI/CD system, those calls can be authenticated properly.

We can manually generate and register an Issuer in a multi-step process described here, however the Fusebit CLI provides a a simple initialization flow automates the process.

fuse client init {client id}

This command will create an Issuer and associate it with the given Client. It will also generate a one-time use token that can be used to initialize a new installation of the CLI, for example for use on your CI/CD machine.

Setting up a CI/CD Machine Directly

Execute the following command with the initialization token generated in the previous step on that machine. This will set up the CLI instance to act on behalf of the Client we created earlier.

fuse init {token}

Setting up on CI/CD Infrastructure

If you are running your CI/CD on cloud infrastructure such as GitHub Actions, do the following instead:

  1. Run the following locally on your development machine. This will save it under that profile name in the local environment, which you then need to export to your target CI/CD platform.
fuse init {token} -p {profile name}
  1. Use the following command to output to the console a JSON bundle, including the private keys for that profile.
fuse profile export {profile name}
  1. Securely transfer this JSON bundle to the target environment's secret store, and then feed it into
fuse profile import

🚧

Transferring Profiles Securely

The JSON profile bundle contains keying material that grants access to your Fusebit resources. Make use of your CI/CD platforms secret storage mechanisms to safely provide that secret to your automation.

We also recommend that the JSON bundle is Base64 encoded while in transit to avoid any potential shell escape issues.

fuse profile export | base64 > profile_export.b64

# If the profile is stored on disk
cat profile_export.b64 | base64 -d | fuse profile import production

# If the profile is stored in an environment variable
echo ${FUSEBIT_PROFILE_BUNDLE} | base64 -d | fuse profile import production

Reading data      │  Reading input data from STDIN...

Profile Imported  │  The 'production' profile was successfully written

production        │  Type: PKI
                  │  Deployment: https://api.us-west-1.on.fusebit.io
                  │  Account: acc-7a7faa6fbcde4332
                  │  Subscription: sub-041ebbcdefb34ebe
                  │  Issuer:
                  │  f90bac4b.usr-d30d32e6e1234536.api.us-west-1.on.fusebit.io
                  │  Created: 8/2/2021, 12:46:47 PM • Last Updated: 8/2/2021,
                  │  12:46:47 PM

The setup is now complete, and you should be able to easily execute CI/CD tasks using a CLI instance configured as the Client we created in this guide.

Because the Client's Issuer is using an uploaded set of public/private keys, the CLI instance will never need to re-authenticate, as long as the Issuer it is using remains trusted by Fusebit (ie, as long as you don't delete it from the system).

FAQ

Using the profile results in 403 errors

This is an indication that the client did not have the necessary permissions attached to it.

Run the command fuse client get {client id}. If there is not an Allow section in the output, then follow the steps in Granting Access to a Client to grant permissions to that client.

The CI/CD platform reports back error:0909006C:PEM routines:get_name:no start line

This is commonly caused by escape characters or other encoding conflicts between the profile and how it's presented to the CI/CD platform.

A common way to work around this is to base64 encode the JSON profile object in transit:

fuse profile export | base64 > profile.b64

# Place the contents of profile.b64 in the secret management platform
# for your CI/CD, and load it in within the task.

cat profile.b64 | base64 -d | fuse profile import

This can simplify the transference of the profile substantially between systems and environments.


Did this page help you?