Quick start#
This section gives you 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:
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
This will install:
The
union
SDKThe
flytekit
SDK
Configure 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 the ~/.union/config.yaml
with the configuration information to connect to your Union instance.
Note
These directions apply to Union BYOC, where you connect to your own dedicated Union instance. To configure a connection to Union Serverless, see the Serverless version of this page.
By default, the union
CLI will look for a configuration file at ~/.union/config.yaml
. (See union CLI for more details.)
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.
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:
Note
When you use union create login --host <union-host-url>
to configure the union
CLI, this creates a config.yaml
file
configured for a Proof Key of Code Exchange (PKCE) mechanism. This is one of three authentication options, including DeviceFlow and
ClientSecret. In short, PKCE opens a browser window allowing you to login, DeviceFlow returns a URL you can navigate to,
and ClientSecret authenticates via a pre-configured secret. If you are using Union in a headless fashion, either on a
VM, connecting to a machine via SSH, in CI/CD, etc., DeviceFlow and ClientSecret should be considered.
See CLI authentication for more information.