Advanced Deployer Usage

Programmatic Configuration

The SDK Deployer can be used programmatically via the newDeployerParameters builder and runDeployment() function. Configuration parameters are then added as camelCase properties instead of kebab-case, as the following code demonstrates:

val parameters = DeployerParameters.newDeployerParameters {
    ownerId = "myCompany"
    environment = "test"
    deployerUser = "testdeployer@testcompany.com"
    // etc.
}

Deployer.runDeployment(parameters)

However, the programmatic approach won’t prompt the user for missing required parameters. An exception is thrown if a required parameter like deployerPwd is missing.

File System Mode

When used programmatically, the Deployer supports a rootDir property that activates a file system mode for looking up resources and secrets. Thus, resources you want to deploy can be located anywhere on your computer instead of the project classpath (i.e., in the project resources directory).

The folder structure of the rootDir must still follow the same structure as the classpath approach, though. For example, if rootDir is set to /Users/myUser/projectName, then your local file system should be set up in the following manner:

Users/
  myUser/
    projectName/
      deployment/
        myCompany/ (1)
          test/ (2)
            resources/
            secrets/
1 Your organizations’s ownerId.
2 The environment you are deploying to.

Diff Reports

The Deployer can generate diff reports by setting the command configuration parameter to diff. For example:

mvn -P deploy-flows -D owner-id=myCompany -D command=diff

When diff is executed, the Deployer will gather all of the local deployment data and compare it to the deployments in the target environment. A directory called deployment-diff-<timestamp> is then created in the build directory of the current working directory. For Maven projects, this would be in the target directory. Otherwise, the build directory is used.

Under the deployment-diff-<timestamp> directory, additional directories are produced for each deployment type: flows, resources, and secrets. Under each deployment type, report directories are created when there are relevant files to review for that report type. An example output might look like the following:

target/
  deployment-diff-2022-03-30_09-15-29/
    flows/
      diff-local/
        payments-flow.json (1)
      diff-test/
        payments-flow.json (1)
      test-only/
        orders-flow.json (2)
    resources/
      unchanged/
        simple-rest-api.json
    secrets/
      local-and-test/
        payment-credentials.json
      test-only/
        order-credentials.json
1 Flow exists locally and in test environment, but content is different.
2 Flow only exists in test environment.

Flows and Resources

The flows and resources directories can contain the following report directories:

Directory Description

unchanged

Contains files for entities that are the same locally and in the target environment.

diff-local
diff-<environment>

Contains files for entities that are currently different locally and in the target environment.

local-only

Contains files for entities that are only present locally and not in the target environment.

<environment>-only

Contains files for entities that are only present in the target environment and not locally.

To see the difference between entities, you can use the diff command line utility in the following manner:

cd target/deployment-diff-2022-03-30_09-15-29/flows/
diff -r diff-*

You can also view the differences from within IntelliJ by selecting the two diff-* directories and pressing Command + D on macOS or Ctrl + D on other OSs.

Secrets

The secrets directory is a little different, since you can’t look up and compare the contents of deployed secrets. Thus, the diff report only reflects where the secrets are available. The secrets directory can contain the following report directories:

Directory Description

local-and-<environment>

Contains files for secrets that are present both locally and in the target environment.

local-only

Contains files for secrets that are only present locally.

<environment>-only

Contains files for secrets that are only present in the target environment.
The flow-pattern, resource-pattern, and secrets-pattern filter parameters are also in effect when the diff command is used. The diff report will only contain files for entities that match these regex filters.

Bundles

The Deployer can generate a zip archive of all flow specs (serialized to JSON), resources, and secrets for a given deployment environment by setting the command configuration parameter to bundle. For example:

mvn -P deploy-flows -D owner-id=myCompany -D command=bundle

The archive is created in the project’s target directory with the naming pattern flow-deployment-<ownerId>-<environment>-<timestamp>.zip. The extracted archive will have the following directory layout:

deployment/
  myCompany/
    environment/
      flows/
      resources/
      secrets/

The generated archive can then be added to a Beatbox installation to easily deploy all flows and resources. See the Beatbox deployment guide for more details.

Encrypted values are not decrypted when bundling secrets, even if the decryption-key parameter is set. Such values must be decrypted when they are deployed, not when bundled.