Quick start

Quick start#

In this section, we give a quick introduction to writing and running Union workflows.

Gather your credentials#

After your administrator has onboarded you to Union, you should have the following at hand:

  • Your Union credentials.

  • The URL of your Union instance. We will refer to this as <union-host-url> below.

Log into Union#

Navigate to the UI at <union-host-url> and log in with your credentials. Once you have logged in you should see the Union UI. This is where you will be able to see your workflow executions and and manage your projects:

Union UI

Set up your Python environment#

Set up a Python virtual environment with conda, venv or a similar tool.

Python 3.8 or higher is required. Python 3.11 is the current recommended version.

Install conda using Miniconda, then run the following to create a new Python environment:

$ conda create -n union-env python=3.11
$ conda activate union-env

Install Python 3.11 from your package manager or from Python.org, then run the following to create a virtual environment:

$ python -m venv .venv
$ source .venv/bin/activate

Install the union package#

After setting up your virtual environment and activating it, install the union Python package:

pip install -U "union[byoc]"

Note

The [byoc] extra package includes configuration defaults specific to Union BYOC that differ from those needed for Union Serverless.

If you are using Union Serverless, you should install union without the [byoc] extra package.

You can tell whether you have the byoc extra package installed by running pip list and checking for the package unionmeta-byoc.

This will install:

Set up configuration for the union CLI#

To register and run workflows on your Union instance using the union CLI, you will need to create a configuration file that contains your Union connection information. To do this, run the following command:

$ union create login --host <union-host-url>

where <union-host-url> is the URL of your Union instance, mentioned above.

This will create a configuration file at ~/.union/config.yaml.

By default, the union CLI will look for a configuration file at ~/.union/config.yaml. You can override this behavior to specify a different configuration file by setting the UNION_CONFIG environment variable:

export UNION_CONFIG=~/.my-config-location/my-config.yaml

Alternatively, you can always specify the configuration file on the command line when invoking union by using the --config flag:

$ union --config ~/.my-config-location/my-config.yaml run my_script.py my_workflow

Warning

If you have previously used Union, you may have configuration files left over that will interfere with access to Union Serverless through the union CLI tool. Make sure to remove any files in ~/.unionai/ or ~/.union/ and unset the environment variables UNIONAI_CONFIG and UNION_CONFIG to avoid conflicts.

union CLI configuration search path#

When using Union BYOC, you should always install the union[byoc] package and not the plain union package, which is is configured for Union Serverless.

This will ensure that the CLI will check for configuration files as follows (if no --config option is specified on the command line):

First, if a --config option is specified on the command line, it will use the file specified there.

Second, the locations pointed to by the following environment variables (in this order):

  • UNION_CONFIG

  • UNIONAI_CONFIG

  • UCTL_CONFIG

Third, the following hard-coded locations (in this order):

  • ~/.union/config.yaml

  • ~/.uctl/config.yaml

If none of these are present, it will raise an error. It will not attempt to connect to serverless.union.ai, as the Serverless version of the CLI would.

Create a “Hello, world!” workflow#

To create an example workflow file, copy the following into a file called hello.py:

from flytekit import task, workflow

@task
def say_hello(name: str) -> str:
    return f"Hello, {name}!"

@workflow
def hello_world_wf(name: str = 'world') -> str:
    res = say_hello(name=name)
    return res

Tasks and workflows#

The “Hello, world!” code contains a task and a workflow, which are Python functions decorated with the @task and @workflow decorators, respectively. For more information, see the task and workflow documentation.

Run the workflow locally in Python#

You can run the workflow in your local Python environment with the union run command:

$ union run hello.py hello_world_wf

You should see the following output:

Running Execution on local.
Hello, world!

Since the @workflow function takes an argument called name, you can also pass that in as a command-line argument like this:

$ union run hello.py hello_world_wf --name Ada

You should see the following output:

Running Execution on local.
Hello, Ada!

Run the workflow remotely on Union#

To run the workflow remotely on Union, add the --remote flag:

$ union run --remote hello.py hello_world_wf --name "Ada"

The output displays a URL that links to the workflow execution in the UI:

[✔] Go to https://<union-host-url>/org/... to see execution in the UI.

Go to the UI to see the execution:

Dashboard

Contents