Connection Resource

About

The Connection resource let’s you store pre-configured inputs for a Task. This is commonly used to store connection information to a remote system. Connections can also be associated with a Vault secret. You can use stored connections in flows to connect to remote systems with more comfort.

Simple example

Create a connection for the GIT task type and call it „library“. Enter the following into the value field:

ref: develop
command: metadata
repository_url: 'https://github.com/starflows/library.git'

Next, create a new flow to use the connection and call it „connection-test“. Use the following script:

import flow_api
def handler(system: flow_api.System, this: flow_api.Execution):
    metadata = this.connect('library').get('output_value')
    this.log(metadata['date_str'])
    return this.success('all done')

Override inputs

You can override inputs which are stored in the connection by specifying different values when using the connection. Let’s modify the „connection-test“ flow from before to read information for a different ref:

import flow_api
def handler(system: flow_api.System, this: flow_api.Execution):
    metadata = this.connect('library', ref='v2').get('output_value')
    this.log(metadata['date_str'])
    return this.success('all done')

Attach vault secrets

To be able to attach secrets to a connection object, a working vault integration must be configured beforehand.

To associate a connection object with a vault secret, use the Attach secret button in the user interface. You will be asked to specify the path of the secret which will be fetched from your vault when the connection is used.

Let’s assume there is a vault secret stored in the path secret/oracle which contains two keys:

user: my-user
password: my-secret-password

Create a connection for the SQLORACLE task type, call it „oracle“ and enter the following into the value field:

host: my-oracle-server
service_name: xe

Click on Attach secret and enter secret/data/oracle as the path to the secret

This assumes that the secret store being used in vault is of type key-value version 2. You can find more information about vault secret engines at https://www.vaultproject.io/api-docs/secret

When the connection is being used all keys of the secret are applied to the input stored in the connection:

import flow_api
def handler(system: flow_api.System, this: flow_api.Execution):
    oracle_db_version = this.connect(
        'oracle',
        execute='SELECT * FROM v$version',
    ).get('output_value')['result']
    this.log(oracle_db_version)
    return this.success('all done')

Order of input application

Inputs for a task execution can be specified in different places. Inputs from all places are merged into one combined input set before being used by the task. Inputs are applied in the following order:
  1. Value of the connection
  2. Vault secrets associated with the connection
  3. Inputs specified in the flow script
Inputs which are applied later can override keys of inputs which were applied before. If, for example, the connection specifies a key port and the vault secret also contains a key port, the value of the vault secret will be used.