SDK Deployer

Overview

The SDK’s built-in Deployer will collect local flow specifications, secrets/credentials, and resources (like OpenAPI and WSDL documents) and deploy them to a remote flow-server.

The SDK example project includes a Maven profile configuration that provides easy access to the Deployer class. It can be used from the command line in the following manner:

mvn -P deploy-flows -D owner-id=myCompany -D environment=test
If you are not using the example project, you can still copy the same Maven profile config into your own project, or programmatically configure the Deployer instead. See the Advanced Usage documentation for more details.

After deployment, you can monitor and manage flow access from the Utilihive Console. Refer to the Management documentation for specifics on using the Console.

Configuration

Configuration parameters can be supplied to the Deployer in a number of ways. These include the following methods, in order of precedence:

Method Description

Environment variables

Typically set for automatic deployments by CI systems.

Java system properties

Set on the command line with the -D option when the deployment process is started (e.g., -D property=value).

Property files

A classpath resource located at /deployment/{ownerId}/{environment}/deployer.properties with properties defined per line as property=value. Can optionally fall back on default values defined in /deployment/{ownerId}/_common-env/deployer.properties.

Prompted input

If required parameters are not made available from any of the above sources, the Deployer will prompt the user for these values before continuing.
If you want to have a fully automatic deployment, make sure you provide all required parameters via environment variables, system properties, and/or property files.

Required Parameters

The following Deployer parameters are required:

Parameter Description Set by

owner-id

ID of the customer organization owning the deployments. ID is provided by Greenbird.

Environment variable
System property
Prompt

environment

Environment to deploy to. Used to specify which datasets and configurations to deploy.

Environment variable
System property
Prompt

authentication-method

The authentication method to be used by the deployer. Legal values are Oauth2PasswordGrant (default), Oauth2CodeGrant or Oauth2ClientCredentialGrant.

Environment variable
System property
Property file

management-api-root

Root URI for the Utilihive Customers Management API (e.g., https://api.dev.utilihive.io). Used to manage deployments.

Environment variable
System property
Property file
Prompt

Depending on the value provided for authentication-method above, the following parameters are available (required parameters are marked with *).

OAuth2 with Password Grant

Parameter Description Set by

deployer-user*

Developer’s username. User must have the Admin or Deployer role for the selected owner and environment. See the User documentation for help.

Environment variable
System property
Property file
Prompt

deployer-pwd*

Developer’s password.

Environment variable
System property
Property file
Prompt

identity-api-root*

Root URI for the Utilihive Identity API (e.g., https://api.dev.utilihive.io/metercloud-integration-identity/api). Used to provide access tokens to the Deployer.

Environment variable
System property
Property file
Prompt

OAuth2 with Code Grant

A description of this authentication method may be found in The OAuth 2.1 Authorization Framework.

Parameter Description Set by

client-id*

The client ID identifying the client at the authorisation server.

Environment variable
System property
Property file
Prompt

client-secret

The (optional) client secret authenticating the client at the authorisation server.

Environment variable
System property
Property file
Prompt

authentication-endpoint*

URL to the user authentication endpoint of the authorization server.

Environment variable
System property
Property file
Prompt

token-endpoint*

URL to the token endpoint of the authorization server.

Environment variable
System property
Property file
Prompt

callback-endpoint

Callback endpoint used by the authorization server upon successful authentication. Defaults to http://127.0.0.1:3000/callback.

Environment variable
System property
Property file

scope

Scope requested. Default to openid.

Environment variable
System property
Property file

OAuth2 with Client Credential Grant

A description of this authentication method may be found in The OAuth 2.1 Authorization Framework.

Parameter Description Set by

client-id*

The client ID identifying the client at the authorisation server.

Environment variable
System property
Property file
Prompt

client-secret*

The client secret authenticating the client at the authorisation server.

Environment variable
System property
Property file
Prompt

token-endpoint*

URL to the token endpoint of the authorization server.

Environment variable
System property
Property file
Prompt

scope

Scope requested. Default to openid.

Environment variable
System property
Property file

Optional Parameters

The following Deployer parameters are optional:

Parameter Description Set by

decryption-key

Decryption key used to decrypt sensitive values stored in property files.

Environment variable
System property

groups

Comma separated list of flow groups to select for deployment. All flows will be selected if not set. Flows can be associated with groups by using the group() flow spec builder function.

Environment variable
System property
Property file

flow-scan-root

Root package/directory to scan for flow specs (e.g., com.mycompany.flows). Improves the performance of flow scanning.

Environment variable
System property
Property file

flow-pattern

Regular expression used to filter flows to be processed by flow ID (e.g., orders-.*). If set, only matching flows will be considered. Resources and secrets will be excluded unless those filters are also set.

Environment variable
System property
Property file

resource-pattern

Regular expression used to filter resources to be processed by resource ID (e.g., orders-.*). If set, only matching resources will be considered. Flows and secrets will be excluded unless those filters are also set.

Environment variable
System property
Property file

secrets-pattern

Regular expression used to filter secrets to be processed by secrets key (e.g., orders-.*). If set, only matching secrets will be considered. Flows and resources will be excluded unless those filters are also set.

Environment variable
System property
Property file

dry-run

Run the process, but skip all mutating operations. Default: false.

Environment variable
System property
Property file

forced

Deploy flows and resources even if they are not outdated on the server. Default: false.

Environment variable
System property
Property file

command

Which operation the Deployer should execute. Either deploy (default), delete, diff, or bundle. See Advanced Usage for more details on using diff and bundle.

Environment variable
System property
Property file

tls-certificate-authority-pem

The certificate or certificate authority to be added to the trust store, in PEM format. This property may be used when the received server certificate is not trusted (self-signed, issued by untrusted Certificate Authority, etc). PEM is a multi-line format, so it’s recommended to provide this as an environment variable or in the property-file.

See Untrusted Server Certificate below for more information.

Environment variable
System property
Property file
Parameter names can also be given in a portable environment variable format by using uppercase letters and underscores. For example, IDENTITY_API_ROOT instead of identity-api-root.

Untrusted Server Certificate

Server certificates are used for encrypting data transmitted between the SDK deployer and its services, mainly the Management API (management-api-root) and sometimes identity providers (identity-api-root or token-endpoint).

In most cases, the servers are using commonly trusted certificates. However, in certain cases like when behind a corporate firewall, you might see an output similar to the following:

Certificate received from server is invalid or not trusted
*************************************************************************
** Server certificate received from URI:
** - https://self-signed.badssl.com
**
** Certificate:
-----BEGIN CERTIFICATE-----
MIIDazCCAlOgAwIBAgIJAIfapJYDdpjZMA0GCSqGSIb3DQEBCwUAMFQxCzAJBgNV
....
lfqi0kpfq9CPdqqX6pZi
-----END CERTIFICATE-----
** If you trust the above server certificate, you can add the certificate
** to your truststore by setting the 'tls-certificate-authority-pem' property in the
** deployment configuration OR by providing the environment variable
** TLS_CERTIFICATE_AUTHORITY_PEM (see examples below).
**
** As property in deployer.properties file:
tls-certificate-authority-pem=-----BEGIN CERTIFICATE-----\n\
MIIDazCCAlOgAwIBAgIJAIfapJYDdpjZMA0GCSqGSIb3DQEBCwUAMFQxCzAJBgNV\
....\n\
-----END CERTIFICATE-----

**
** As environment variable:
export TLS_CERTIFICATE_AUTHORITY_PEM=$'-----BEGIN CERTIFICATE-----
MIIDazCCAlOgAwIBAgIJAIfapJYDdpjZMA0GCSqGSIb3DQEBCwUAMFQxCzAJBgNV
....
-----END CERTIFICATE-----'
*************************************************************************

In such a case, you should evaluate if the server certificate can be trusted. If trusted, add the certificate to the tls-certificate-authority-pem property mentioned above.

In some cases you will see that multiple certificates are printed (the certificate is part of a trust chain). In this case you must only add the part of the certificate chain that is common for all the backend services the deployer communicates with, typically the root CA. In this case you will find this info in the printed output.

** Server certificate received from URI:
** - https://tls-v1-2.badssl.com:1012/
**
** Certificate summary
** 2 certificate(s) in chain (root at bottom):
** Certificate #1 issuer: CN=R11,O=Let's Encrypt,C=US (valid to: Thu Nov 07 16:05:43 CET 2024)
   Subject Alternative Names: *.badssl.com, badssl.com

** Certificate #2 issuer: CN=ISRG Root X1,O=Internet Security Research Group,C=US (valid to: Sat Mar 13 00:59:59 CET 2027)

**
** IMPORTANT: The end certificate was part of a certificate chain.
** It is very likely that the backends the deployer communicates with have
** different certificates, that share a common root or intermediate certificate
** authority. In this case you must only add the root (or shared part) of the
** certificate chain to your configuration.
**
** Certificate:
-----BEGIN CERTIFICATE-----
MIIE9TCCA92gAwIBAg...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIFBjCCAu6gAwIBAg...
-----END CERTIFICATE-----

...

** Only root-certificate as property in deployer.properties file:
tls-certificate-authority-pem=-----BEGIN CERTIFICATE-----\n\
MIIFBjCCAu6gAwIBAg...
-----END CERTIFICATE-----

** Only root-certificate as environment variable:
export TLS_CERTIFICATE_AUTHORITY_PEM=$'-----BEGIN CERTIFICATE-----
MIIFBjCCAu6gAwIBAg...
-----END CERTIFICATE-----'
*************************************************************************

Directory Layout

The location of deployable flow specs in your project depends on if the flow-scan-root parameter is set. Otherwise, the entire classpath is scanned.

All other deployment files—​resources, secrets, configurations—​are stored as classpath resources. In a standard Kotlin project, these would fall under the src/main/resources/ directory. From there, data is looked up via the path template /deployment/{ownerId}/{environment}/{dataType}/. The path template has the following parameters:

Parameter Description

ownerId

ID of the organization the deployments belong to. ID is assigned by Greenbird.

environment

Environment the resources are to be deployed to (e.g., production). Also supports a special _common-env environment directory. Any data found in _common-env will be added to the dataset for the target environment. If data exists in both places, the target environment directory will take precedence.

dataType

Can be either flowconfig, resources, or secrets. Deployment data is loaded from relevant files found under this directory and all subdirectories. Thus, you are free to organize the files in this directory however you see fit.

An example file structure might look like the following:

main/
  kotlin/
    flows/
      SimpleRestFlow.kt
  resources/
    deployment/
      myCompany/
        _common-env/ (1)
          resources/
            echo-api-v1.json
            echo-api-v1.properties
          deployer.properties
        production/ (2)
          resources/
            openapi/
              simple-rest-api.json
              simple-rest-api.properties
            wsdl/
              soap-num-conversion.wsdl
              soap-num-conversion.properties
          secrets/
            backendAuth.properties
          deployer.properties
1 Properties used by, and resources deployed to, all environments.
2 Properties used by, and resources/secrets deployed to, only the production environment.

Deployer Properties

Configuration parameters like flow-scan-root can be defined in a properties file alongside your other deployment data. This is a good approach for providing static values like the service root URIs. This file is located at /deployment/{ownerId}/{environment}/deployer.properties.

Deployer properties apply to the _common-env directory, as well. Thus, global configurations can be placed under _common-env, which will be merged with the more targeted environment properties.

Deployment Types

The three types of deployable entities include flow specifications, resources, and secrets. By default, the Deployer will look for all available types, unless a *-pattern parameter is used. Each type must follow a certain structure to be considered deploy-ready.

Flow Specs

The Deployer will scan the classpath for flow spec factory functions annotated with @FlowDeploy. For example, the following factory function copies a flow spec and overrides the ownerId for deployments:

@FlowDeploy
fun simpleRest(): FlowSpecConfig = simpleRestSpec.copy(
    ownerId = "myCompany"
)

The annotation can optionally be configured with a list of target environments the flow is allowed to be deployed to (e.g., @FlowDeploy(["dev", "staging"])). If a list is not provided, the given flow will be deployed to whatever environment the Deployer is deploying to.

Resources

Deploying a resource, like an OpenAPI spec, requires two files to be present. The first file is the resource itself (e.g., <resourceId>.json). The second file contains the resource’s metadata and is similarly named <resourceId>.properties.

For example, if your flow uses a resource with an ID of simple-rest-api, then your /deployment/{ownerId}/{environment}/resources/ folder would contain the following files:

  • simple-rest-api.json

  • simple-rest-api.properties

The properties file can contain the following metadata:

Property Description

type

Resource type. Required. Must be a type supported by the Utilihive Resource Registry (e.g., OpenAPIv3 or WSDLv1).

shortDescription

Summary description of the resource. Optional.

fullDescription

Full description of the resource. Optional.

changeComment

Change comment for this revision of the resource. Optional.

Secrets

Secrets are deployed as a single file named <secretKey>.properties in any /deployment/{ownerId}/{environment}/secrets/ directories. The secretKey should match the key supplied to the authenticationConfigKey property on the processors that use these credentials (e.g., backendAuth.properties).

The properties in the file must be in a format supported by Utilihive’s authentication system. See the Secret Types documentation for available formats. The required properties description and changeComment can be omitted as the Deployer sets these automatically using default values. However, _description_ property can be included to provide a custom description. changeComment is always set by the Deployer. If the .properties file contains a _type_ property, the Deployer will perform validation on the specified type.

For example, the following secret would fail deployment, because an ApiKey type requires an apiKeyValue property:

_type_=ApiKey
apiKeyName=myKey
apiKeyLocation=Header

Never commit plain text passwords to your version control system. If you wish to include passwords in a properties file, encrypt the value first. The SDK includes encryption tools that you can use for this purpose. The encrypted value would then be enclosed in ENC(), as the following demonstrates:

userName=orderAdmin
password=ENC(adajdnkLneubaibaa98hr39bnasdkba937rab)

The Deployer uses the decryption-key parameter to decrypt the value when needed. If this parameter is not set, deploying ENC() enclosed values will fail.

Flow Deployment Context

The flow spec factory function can optionally capture a single parameter of the type FlowDeploymentContext. For example:

@FlowDeploy
fun ordersFlow(ctx: FlowDeploymentContext): FlowSpecConfig {
  ...
}

Deployment Configurations

Among other things, the flow deployment context provides a flowDeploymentConfig() function for building a strongly typed configuration instance. Given the following data class that inherits from DeploymentConfiguration:

data class OrderPlacementConfig(
    val address: String,
    val timeout: Long?
) : DeploymentConfiguration

The context could be used in the following manner:

val flowConfig = ctx.flowDeploymentConfig(
    configType = OrderPlacementConfig::class,
    flowConfigId = ordersFlowSpec.id
)

val flowToDeploy = ordersFlowSpec.map<RestRequestConfig> { restRequestConfig ->
    restRequestConfig.copy(address = URL(flowConfig.address))
}

The values of the flowConfig object are populated by matching property files. Flow configuration properties are stored in /deployment/{ownerId}/{environment}/flowconfig/ directories, similar to resources and secrets. The name of the file should follow the format <flowConfigId>.properties. The flowConfigId can be an actual flow ID if the configuration is flow specific (e.g., orders-flow.properties) or a more generic ID if the properties are re-used across flows.

In the above example, the properties file would need to include an address property. The timeout property, if omitted, would be set to null, since the data class defined it as nullable.

Fallback Properties

Common, reusable values can also be defined in a property file specifically named _common-flowconfig.properties. This file can be defined in the target environment directory or the _common-env directory. If the file is found in both places, the target environment takes precedence.

On the Kotlin side, use the @Fallback annotation to designate that a property can resort to the shared property value if the flow-specific property can’t be found. For example:

data class OrderPlacementConfig(
    @Fallback("fallbackAddress")
    val address: String,
    val timeout: Long?
) : DeploymentConfiguration

Deleting Entities

The delete command only operates on entities already deployed to the flow-server and will not consider local classpath data. Deletion checks if any of the filter parameters (flow-pattern, resource-pattern, etc.) are set and, if so, deletes the matching entities.

For example, the following command would delete the deployed flow called simple-rest:

mvn -P deploy-flows -D command=delete -D flow-pattern=simple-rest
Always use the dry-run parameter first before performing the actual deletion to ensure you only affect the intended entities.